/ Hex Artifact Content
Login

Artifact e9a463ea16100b54f02b4063dc96a0add392c4a92963c50bfd6eb0324e118f3b:


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 6c 73 65 0a 23 20 64  nt N);.#else.# d
1e00: 65 66 69 6e 65 20 73 71 6c 69 74 65 33 5f 63 6f  efine sqlite3_co
1e10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1e20: 28 58 29 20 30 0a 23 20 64 65 66 69 6e 65 20 73  (X) 0.# define s
1e30: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1e40: 74 69 6f 6e 5f 67 65 74 28 58 29 20 20 28 28 76  tion_get(X)  ((v
1e50: 6f 69 64 2a 29 30 29 0a 23 65 6e 64 69 66 0a 0a  oid*)0).#endif..
1e60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e70: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1e80: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1e90: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1eb0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ec0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1ed0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1ee0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1ef0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1f00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1f10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1f20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1f40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1f50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1f60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1f70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1f80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1f90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1fa0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1fb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1fc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1fd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1fe0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1ff0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
2000: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
2010: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2020: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
2030: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
2040: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
2050: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
2060: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
2070: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
2080: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
2090: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
20a0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
20b0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
20c0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
20d0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
20e0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
20f0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
2100: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
2110: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
2120: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
2130: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
2140: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
2150: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
2160: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
2170: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
2180: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
2190: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
21a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
21b0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
21c0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
21d0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
21e0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
21f0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
2200: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
2210: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
2220: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2230: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
2240: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
2250: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2260: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
2270: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
2280: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
2290: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
22a0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
22b0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
22c0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
22d0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
22e0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
22f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2300: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2310: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2320: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2330: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2340: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2350: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2360: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2370: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2380: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2390: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
23a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
23b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
23c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
23d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
23e0: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72  LIZED].  ^(The r
23f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2400: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
2410: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
2420: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
2430: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2440: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
2450: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
2460: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
2470: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
2480: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
2490: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
24a0: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
24b0: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
24c0: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
24d0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
24e0: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
24f0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2500: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
2510: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
2520: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
2530: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2540: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2550: 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ation..*/.int sq
2560: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2570: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
2580: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2590: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
25a0: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
25b0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
25c0: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
25d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
25e0: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
25f0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2600: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2610: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2620: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2630: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
2640: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
2650: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
2660: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
2670: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
2680: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
2690: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
26a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
26b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
26c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
26d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
26e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
26f0: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2700: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2710: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2720: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2730: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
2740: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2750: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
2760: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
2770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2790: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27a0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
27b0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
27c0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
27d0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
27e0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
27f0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2800: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2810: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2820: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2830: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
2840: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
2850: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
2860: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
2870: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
2880: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
2890: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
28a0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
28b0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
28c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
28d0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
28e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
28f0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2900: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2920: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2930: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
2940: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
2950: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
2960: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
2970: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2980: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
2990: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
29a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
29b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
29c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
29d0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
29e0: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
29f0: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2a00: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2a10: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2a20: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2a30: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
2a40: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2a50: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
2a60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2a70: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2a80: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
2a90: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2aa0: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2ab0: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2ac0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2ad0: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2ae0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2af0: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2b00: 34 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54  4;.# ifdef SQLIT
2b10: 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  E_UINT64_TYPE.  
2b20: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2b30: 5f 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  _UINT64_TYPE sql
2b40: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c  ite_uint64;.# el
2b50: 73 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66  se  .    typedef
2b60: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
2b70: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2b80: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64  te_uint64;.# end
2b90: 69 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  if.#elif defined
2ba0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
2bb0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
2bc0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
2bd0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2be0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2bf0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2c00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2c10: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2c20: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2c30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2c50: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2c60: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2c70: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2c80: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2c90: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2ca0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2cb0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2cc0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2cd0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2ce0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2cf0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2d00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2d10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2d20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2d30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2d40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2d50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2d60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2d70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2d80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2d90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2da0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
2db0: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
2dc0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2dd0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2de0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
2df0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
2e00: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
2e10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2e20: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2e30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2e40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2e50: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
2e60: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
2e70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2e80: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
2e90: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
2ea0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
2eb0: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
2ec0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ed0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
2ee0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ef0: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
2f00: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2f10: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
2f20: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
2f30: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2f40: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
2f50: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
2f60: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
2f70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f80: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
2f90: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
2fa0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
2fb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2fc0: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
2fd0: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2fe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2ff0: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
3000: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
3010: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
3020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3030: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
3040: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
3050: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
3060: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
3070: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
3080: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
3090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
30a0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
30b0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
30c0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
30d0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
30e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
30f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
3100: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
3110: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
3120: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
3130: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
3140: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
3150: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
3160: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
3170: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
3180: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
3190: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
31a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31b0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
31c0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
31d0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
31e0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
31f0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
3200: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3210: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
3220: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
3230: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
3240: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
3250: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
3260: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
3280: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
3290: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
32a0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
32c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
32d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32e0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
32f0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3300: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3310: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3320: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3340: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3350: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
3360: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
3370: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3380: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3390: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
33a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
33b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
33c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
33d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
33e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
33f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3400: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3410: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3420: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3440: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3450: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3460: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3470: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3480: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
34a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
34c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
34d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
34e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
34f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3500: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3510: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3520: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3530: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3540: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3550: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3560: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3570: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3580: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3590: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
35a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
35b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
35c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
35d0: 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
35e0: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
35f0: 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
3600: 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33  close_v2(sqlite3
3610: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
3620: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
3630: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
3640: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
3650: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
3660: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
3670: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
3680: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
3690: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
36a0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
36b0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
36c0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
36d0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
36e0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36f0: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
3700: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
3710: 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f  terface.** METHO
3720: 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
3730: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3740: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3750: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3760: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3770: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3780: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3790: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
37a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
37b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
37c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
37d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
37e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
37f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3800: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3810: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3820: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3830: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3840: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3850: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3860: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3870: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3880: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3890: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
38a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
38b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
38c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
38e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
38f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3900: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3910: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3920: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3930: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3940: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3950: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3960: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3970: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3980: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3990: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
39a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
39b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
39c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
39d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
39e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
39f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3a00: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3a10: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3a20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3a30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3a40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3a50: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3a60: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3a70: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3a80: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3a90: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3aa0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
3ab0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
3ac0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3ad0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3ae0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3af0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3b00: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3b10: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3b20: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3b30: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3b40: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3b50: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3b60: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3b70: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3b80: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3b90: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3ba0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
3bb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
3bc0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
3bd0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3be0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3bf0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3c00: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3c10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3c20: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3c30: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3c40: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3c50: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3c60: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3c70: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3c80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61  sqlite3_exec() a
3c90: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
3ca0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
3cb0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3cc0: 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74  d..** ^If the 5t
3cd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3cf0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f   not NULL and no
3d00: 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72   errors.** occur
3d10: 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65  , then sqlite3_e
3d20: 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70  xec() sets the p
3d30: 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74  ointer in its 5t
3d40: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
3d50: 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65  * NULL before re
3d60: 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  turning..**.** ^
3d70: 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78  If an sqlite3_ex
3d80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65  ec() callback re
3d90: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
3da0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3db0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
3dc0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f  turns SQLITE_ABO
3dd0: 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b  RT without invok
3de0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ing the callback
3df0: 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69   again and.** wi
3e00: 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e  thout running an
3e10: 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  y subsequent SQL
3e20: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
3e30: 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75  ** ^The 2nd argu
3e40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3e50: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e60: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
3e70: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
3e80: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
3e90: 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72  result.  ^The 3r
3ea0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3eb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3ec0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
3ed0: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3ee0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3ef0: 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66  obtained as if f
3f00: 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
3f10: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
3f20: 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  one for each col
3f30: 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65  umn.  ^If an ele
3f40: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73  ment of a.** res
3f50: 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20  ult row is NULL 
3f60: 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  then the corresp
3f70: 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f  onding string po
3f80: 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a  inter for the.**
3f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fa0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55  callback is a NU
3fb0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
3fc0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3fd0: 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  o the.** sqlite3
3fe0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ff0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
4000: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
4010: 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a  ngs where each.*
4020: 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e  * entry represen
4030: 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63  ts the name of c
4040: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73  orresponding res
4050: 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62  ult column as ob
4060: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
4070: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
4080: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ame()]..**.** ^I
4090: 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
40a0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40b0: 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  xec() is a NULL 
40c0: 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74  pointer, a point
40d0: 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74  er.** to an empt
40e0: 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70  y string, or a p
40f0: 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74  ointer that cont
4100: 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73  ains only whites
4110: 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20  pace and/or .** 
4120: 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68  SQL comments, th
4130: 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d  en no SQL statem
4140: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
4150: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
4160: 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ase.** is not ch
4170: 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73  anged..**.** Res
4180: 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a  trictions:.**.**
4190: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
41a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
41b0: 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
41c0: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
41d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
41e0: 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20  ().**      is a 
41f0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b  valid and open [
4200: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4210: 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ion]..** <li> Th
4220: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
4230: 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
4240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
4250: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
4260: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
4270: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
4280: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4290: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
42a0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
42b0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
42c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
42d0: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
42e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
42f0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
4300: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
4310: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
4320: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
4330: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
4340: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
4350: 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
4360: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4370: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4380: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4390: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
43a0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
43b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
43e0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
43f0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4410: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4420: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4430: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4460: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4470: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4480: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4490: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
44a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44b0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
44c0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
44d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
44e0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
44f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4500: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4510: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
4520: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4530: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4540: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4550: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4560: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4570: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
4580: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
4590: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
45a0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
45b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
45c0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
45d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
45e0: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
45f0: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4600: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
4620: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4630: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4640: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4650: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4670: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4680: 20 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f   /* Generic erro
4690: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
46a0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
46b0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
46c0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
46d0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
46f0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
4700: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
4710: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4720: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4730: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4740: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4750: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4770: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4780: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4790: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
47a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47b0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
47c0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
47d0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
47e0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
4800: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
4810: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4820: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4830: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4840: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4850: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4860: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4880: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4890: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
48a0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
48b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
48c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48d0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
48e0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
48f0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
4900: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
4910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4920: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4930: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4940: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4950: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4960: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4970: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
4980: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
4990: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
49a0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
49b0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
49c0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
49d0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
49e0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
49f0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4a00: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4a10: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4a20: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
4a30: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4a50: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4a60: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4a70: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4a90: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4aa0: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20  /* Internal use 
4ab0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
4ac0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4ad0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4ae0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4af0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4b00: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
4b10: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
4b20: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
4b30: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
4b40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
4b60: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4b70: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4b80: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4b90: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4ba0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4bb0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4bc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4bd0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4be0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4bf0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4c00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c10: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
4c20: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
4c30: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
4c40: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
4c50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
4c60: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4c70: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4c80: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4c90: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4ca0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74       24   /* Not
4cb0: 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
4cc0: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
4cd0: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
4ce0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
4cf0: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
4d00: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
4d10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
4d20: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
4d30: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
4d40: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
4d50: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4d60: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20  SQLITE_NOTICE   
4d70: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66     27   /* Notif
4d80: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71  ications from sq
4d90: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
4db0: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f  RNING     28   /
4dc0: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20  * Warnings from 
4dd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4df0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
4e00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4e10: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
4e20: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
4e30: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
4e40: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
4e50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4e60: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
4e70: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
4e80: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4e90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4ea0: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
4eb0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4ec0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
4ee0: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e  itions}.**.** In
4ef0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4f00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4f10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4f20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30  return one of 30
4f30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73   integer.** [res
4f40: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4f50: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4f60: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
4f70: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
4f80: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4f90: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
4fa0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
4fb0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
4fc0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
4fd0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
4fe0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
4ff0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
5000: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
5010: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
5020: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
5030: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
5040: 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e  3.3.8 [dateof:3.
5050: 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65  3.8].** and late
5060: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
5070: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
5080: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
5090: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
50a0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
50b0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
50c0: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
50d0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
50e0: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
50f0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
5100: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
5110: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
5120: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
5130: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
5140: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
5150: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
5160: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
5170: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
5180: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
5190: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
51a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
51b0: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
51c0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
51d0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53  SQLITE_ERROR_MIS
51e0: 53 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28  SING_COLLSEQ   (
51f0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28  SQLITE_ERROR | (
5200: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5210: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52  QLITE_ERROR_RETR
5220: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  Y             (S
5230: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32  QLITE_ERROR | (2
5240: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5250: 4c 49 54 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53  LITE_ERROR_SNAPS
5260: 48 4f 54 20 20 20 20 20 20 20 20 20 20 28 53 51  HOT          (SQ
5270: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c  LITE_ERROR | (3<
5280: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5290: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
52a0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
52c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
52d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
52e0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
52f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5300: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5310: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5320: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5330: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5350: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5370: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
53a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
53c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
53d0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
53e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
53f0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5410: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5420: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5430: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5450: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5460: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5470: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5490: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
54a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54b0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
54c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54d0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
54e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54f0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5500: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5510: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5520: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5530: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5540: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5550: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5560: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5570: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5580: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5590: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
55a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55b0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
55c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55d0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
55e0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
55f0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5610: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5620: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5630: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5650: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5660: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5670: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5690: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
56a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56b0: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
56c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56d0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
56e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56f0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5710: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5720: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5730: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5750: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5760: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5770: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5780: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5790: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
57a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57b0: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
57c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57d0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
57e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57f0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5810: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5820: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5830: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5840: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5850: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5860: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5870: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5890: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
58a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58b0: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58d0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58f0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5910: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5920: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5930: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5950: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5960: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5970: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5990: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59b0: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
59d0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
59f0: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5a10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5a30: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5a50: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5a70: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5a90: 45 44 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  ED_VTAB         
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
5ab0: 45 44 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64  ED |  (2<<8)).#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5ad0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5ae0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5af0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5b10: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
5b20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5b30: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
5b40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b50: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5b60: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5b70: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
5bc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bd0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5be0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5bf0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
5c20: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
5c30: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5c40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5c60: 44 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28  DIRTYWAL       (
5c70: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5c80: 7c 20 28 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74  | (5<<8)) /* Not
5c90: 20 55 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   Used */.#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5cb0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5cd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5ce0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5cf0: 5f 53 45 51 55 45 4e 43 45 20 20 20 20 20 20 20  _SEQUENCE       
5d00: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5d10: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5d20: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5d30: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5d40: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5d50: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5d70: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5d80: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5d90: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5db0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
5dc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5dd0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
5de0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5df0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5e00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e10: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5e20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e30: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49  E_READONLY_CANTI
5e40: 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54  NIT       (SQLIT
5e50: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c  E_READONLY | (5<
5e60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5e70: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52  ITE_READONLY_DIR
5e80: 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c  ECTORY      (SQL
5e90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5ea0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5eb0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5ec0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5ed0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5ee0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ef0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5f00: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5f10: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5f20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5f30: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5f40: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5f50: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5f60: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5f80: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5f90: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5fa0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5fc0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5fd0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5ff0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6000: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6010: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
6020: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6030: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
6040: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6050: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
6060: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6070: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
6080: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6090: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
60a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
60b0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
60c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
60d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
60e0: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
60f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
6100: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
6110: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
6120: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
6130: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
6140: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
6150: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
6160: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
6170: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
6180: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61a0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
61b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
61c0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
61e0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
61f0: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
6200: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
6220: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
6230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
6240: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
6260: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
6270: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
6280: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
62a0: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
62b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
62c0: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
62d0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
62e0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
62f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
6300: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
6310: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
6320: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
6330: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
6340: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
6350: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
6360: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
6370: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
6380: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6390: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
63a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
63b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
63c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
63d0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
63e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6410: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6420: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6430: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6450: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
6460: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6470: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
6480: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
64b0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
64c0: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
64d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
64f0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6500: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6520: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6530: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
6540: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
6550: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6560: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
6590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
65b0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
65c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
65d0: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
65e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
65f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6600: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6610: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6620: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6640: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6650: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6660: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
6670: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6680: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
6690: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
66a0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
66b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
66c0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
66d0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
66e0: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
66f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6700: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6710: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6720: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6740: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6750: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
6760: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6770: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6780: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
6790: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
67a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
67b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67c0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
67d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
67e0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
67f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6800: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6810: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6820: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6830: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6840: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6860: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
6870: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
6880: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6890: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
68b0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
68c0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
68d0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
68e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
68f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6900: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6910: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6920: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6930: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
6940: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6950: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
6960: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
6970: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
6980: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
6990: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
69a0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
69b0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
69c0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
69d0: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
69e0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
69f0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6a00: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6a10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6a20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6a30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6a40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6a50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
6a60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
6a70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6a80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
6a90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
6aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6ab0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6ac0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6ad0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6ae0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6af0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6b00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6b10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6b20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6b30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6b40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6b50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6b60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6b70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6b80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6b90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6ba0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6bb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6bc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6bd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6be0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6bf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6c00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6c10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6c20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6c30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6c40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6c50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
6c60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6c70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
6c80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
6c90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
6ca0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
6cb0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6cc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6cd0: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6ce0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6cf0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6d00: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6d10: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6d20: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6d30: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6d40: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6d50: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
6d60: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
6d70: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
6d80: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
6d90: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
6da0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
6db0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6dc0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6dd0: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6de0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6df0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6e00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6e10: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6e20: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6e30: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
6e40: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6e50: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6e60: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6e70: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6e80: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6e90: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6ea0: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6eb0: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6ec0: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6ed0: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6ee0: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
6ef0: 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  leges..**.** The
6f00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41   SQLITE_IOCAP_BA
6f10: 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  TCH_ATOMIC prope
6f20: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 74  rty means that t
6f30: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a  he underlying.**
6f40: 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 70   filesystem supp
6f50: 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69  orts doing multi
6f60: 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 74  ple write operat
6f70: 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20  ions atomically 
6f80: 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72  when those.** wr
6f90: 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ite operations a
6fa0: 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 20  re bracketed by 
6fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
6fc0: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
6fd0: 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
6fe0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54  _FCNTL_COMMIT_AT
6ff0: 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a  OMIC_WRITE]..*/.
7000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7010: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
7020: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7030: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
7040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7050: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
7060: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
7070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7080: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
7090: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
70a0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
70b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70c0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
70d0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
70e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
70f0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
7100: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
7110: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
7120: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
7140: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
7150: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7160: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
7170: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
7180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7190: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
71a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
71b0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
71c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
71d0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
71e0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
71f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7200: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7210: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
7220: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
7230: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7240: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
7250: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
7260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7270: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
7280: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
7290: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
72a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
72b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
72c0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
72d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
72e0: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
72f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
7300: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7310: 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f  _IOCAP_BATCH_ATO
7320: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 78  MIC           0x
7330: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
7340: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
7350: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
7360: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
7370: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
7380: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
7390: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
73a0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
73b0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
73c0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
73d0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
73e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
73f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7400: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
7410: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
7420: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
7430: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
7440: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
7450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
7460: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
7470: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7480: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
7490: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
74a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
74b0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
74c0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
74d0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
74e0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
74f0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
7500: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
7510: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
7520: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7530: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
7540: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
7550: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
7560: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7570: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
7580: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
7590: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
75a0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
75b0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
75c0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
75d0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
75e0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
75f0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
7600: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
7610: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
7620: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
7630: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7640: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
7650: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
7660: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
7670: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
7680: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
7690: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
76a0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
76b0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
76c0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
76d0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
76e0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
76f0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
7700: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
7710: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
7720: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
7730: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7740: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7750: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
7760: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7770: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
7780: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
7790: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
77a0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
77b0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
77c0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
77d0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
77e0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
77f0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
7800: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
7810: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
7820: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
7830: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7840: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7850: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
7860: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
7870: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
7880: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
7890: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
78a0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
78b0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
78c0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
78d0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
78e0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
78f0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
7900: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
7910: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7920: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7930: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7940: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7950: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7960: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7970: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7980: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
7990: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
79a0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
79b0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
79c0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
79d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
79e0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
79f0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
7a00: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
7a10: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7a20: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7a30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7a40: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7a50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7a60: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7a70: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
7a80: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
7a90: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7aa0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7ab0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
7ac0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
7ad0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
7ae0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
7af0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
7b00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7b10: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7b20: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7b30: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7b40: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7b50: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7b60: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7b70: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7b80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7b90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7ba0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7bb0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
7bc0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
7bd0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
7be0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
7bf0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
7c00: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7c10: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7c20: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7c30: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7c40: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7c50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7c60: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7c70: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7c80: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7c90: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7ca0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7cb0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
7cc0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
7cd0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
7ce0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7cf0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
7d00: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7d10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7d20: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7d30: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7d40: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7d50: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7d60: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7d70: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7d80: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7d90: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7da0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7db0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
7dc0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
7dd0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
7de0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
7df0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
7e00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7e10: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7e20: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7e30: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7e40: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7e50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7e60: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7e70: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7e80: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7e90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7ea0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7eb0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
7ec0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
7ed0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7ee0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
7ef0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
7f00: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7f10: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7f20: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7f30: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7f40: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7f50: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7f60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7f70: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7f80: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7f90: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7fa0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7fb0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7fc0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
7fd0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
7fe0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
7ff0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
8000: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
8010: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
8020: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
8030: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
8040: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
8050: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
8060: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
8070: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
8080: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
8090: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
80a0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
80b0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
80c0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
80d0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
80e0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
80f0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
8100: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
8110: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
8120: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
8130: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
8140: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
8150: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8160: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
8170: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8180: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
8190: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
81a0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
81b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
81c0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
81d0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
81e0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
81f0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
8200: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
8210: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
8220: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
8230: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
8240: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
8250: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
8260: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
8270: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
8280: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
8290: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
82a0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
82b0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
82c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
82d0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
82e0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
82f0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
8300: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
8310: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
8320: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
8330: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
8340: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
8350: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
8360: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8370: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
8380: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
8390: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
83a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
83b0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
83c0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
83d0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
83e0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
83f0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
8400: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
8410: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
8420: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
8430: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
8440: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
8450: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
8460: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
8470: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
8480: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
8490: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
84a0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
84b0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
84c0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
84d0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
84e0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
84f0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
8500: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
8510: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
8520: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
8530: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
8540: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
8550: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
8560: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
8570: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
8580: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
8590: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
85a0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
85b0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
85c0: 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c   A [file control
85d0: 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20   opcodes | list 
85e0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
85f0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
8600: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
8610: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
8620: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
8630: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8640: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
8650: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
8660: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
8670: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
8680: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
8690: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
86a0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
86b0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
86c0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
86d0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
86e0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
86f0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
8700: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
8710: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
8720: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
8730: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
8740: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
8750: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
8760: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
8770: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
8780: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
8790: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
87a0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
87b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
87c0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
87d0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
87e0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
87f0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
8800: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
8810: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
8820: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
8830: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
8840: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8850: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
8860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
8870: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
8880: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8890: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
88a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88b0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
88c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88d0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
88e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
88f0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
8900: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8910: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8920: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8930: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
8940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8950: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
8960: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8970: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
8980: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8990: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
89a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
89b0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
89c0: 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e  EN_OPEN].** <li>
89d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
89e0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
89f0: 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  TE].** <li> [SQL
8a00: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
8a10: 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BLE].** <li> [SQ
8a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
8a30: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c  _ATOMIC].** </ul
8a40: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8a50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8a60: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8a70: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8a80: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8a90: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8aa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8ab0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
8ac0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
8ad0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
8ae0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8af0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8b00: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8b10: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8b20: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8b30: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8b40: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8b60: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8b70: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8b80: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8b90: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
8ba0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8bb0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
8bc0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
8bd0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
8be0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8bf0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8c00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8c10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8c20: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8c30: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8c40: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8c50: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8c60: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8c70: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8c80: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8c90: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
8ca0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
8cb0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
8cc0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
8cd0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
8ce0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8cf0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8d00: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8d10: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8d20: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8d30: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8d40: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8d50: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8d60: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8d70: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8d80: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8d90: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
8da0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8db0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
8dc0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
8dd0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
8de0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8df0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8e00: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8e10: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8e20: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8e30: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8e40: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8e50: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8e60: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8e70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8e80: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8e90: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8ea0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8eb0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
8ec0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
8ee0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8ef0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f00: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8f10: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8f20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8f30: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8f40: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8f50: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8f60: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8f70: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8f80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8f90: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
8fa0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
8fb0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
8fc0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
8fd0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
8fe0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8ff0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
9000: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
9010: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
9020: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
9030: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
9040: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
9050: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
9060: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
9070: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
9080: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
9090: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
90a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
90b0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
90c0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
90d0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
90e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
90f0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
9100: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
9110: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
9120: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
9130: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
9140: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
9150: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
9160: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
9170: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
9180: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
9190: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
91a0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
91b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
91c0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
91d0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
91e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
91f0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
9200: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
9210: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
9220: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
9230: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
9240: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
9250: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
9260: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
9270: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
9280: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
9290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
92a0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
92b0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
92c0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
92d0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
92e0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
92f0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
9300: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
9310: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
9320: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
9330: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
9340: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
9350: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
9360: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
9370: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9380: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
9390: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
93a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
93b0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
93c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
93d0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
93e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
93f0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
9400: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9410: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
9420: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
9430: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
9440: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
9450: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
9460: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
9470: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
9480: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
9490: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
94a0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
94b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
94c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
94d0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
94e0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
94f0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
9500: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
9510: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
9520: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
9530: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
9540: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
9550: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
9560: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
9570: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
9580: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
95a0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
95b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
95c0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
95d0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
95e0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
95f0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
9600: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
9610: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9620: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
9630: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
9640: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
9650: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
9660: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
9670: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
9680: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
9690: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
96a0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
96b0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
96c0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
96d0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
96e0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
96f0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9700: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9710: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9720: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9730: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9740: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 4c 49  TE_FCNTL_SIZE_LI
9750: 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  MIT]].** The [SQ
9760: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9770: 4c 49 4d 49 54 5d 20 6f 70 63 6f 64 65 20 69 73  LIMIT] opcode is
9780: 20 75 73 65 64 20 62 79 20 69 6e 2d 6d 65 6d 6f   used by in-memo
9790: 72 79 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 69  ry VFS that.** i
97a0: 6d 70 6c 65 6d 65 6e 74 73 20 5b 73 71 6c 69 74  mplements [sqlit
97b0: 65 33 5f 64 65 73 65 72 69 61 6c 69 7a 65 28 29  e3_deserialize()
97c0: 5d 20 74 6f 20 73 65 74 20 61 6e 20 75 70 70 65  ] to set an uppe
97d0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73  r bound on the s
97e0: 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  ize.** of the in
97f0: 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
9800: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9810: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9820: 61 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  a [sqlite3_int64
9830: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74  ]..** If the int
9840: 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  eger pointed to 
9850: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9860: 6e 20 69 74 20 69 73 20 66 69 6c 6c 65 64 20 69  n it is filled i
9870: 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 63 75  n with the.** cu
9880: 72 72 65 6e 74 20 6c 69 6d 69 74 2e 20 20 4f 74  rrent limit.  Ot
9890: 68 65 72 77 69 73 65 20 74 68 65 20 6c 69 6d 69  herwise the limi
98a0: 74 20 69 73 20 73 65 74 20 74 6f 20 74 68 65 20  t is set to the 
98b0: 6c 61 72 67 65 72 20 6f 66 20 74 68 65 20 76 61  larger of the va
98c0: 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 69 6e  lue.** of the in
98d0: 74 65 67 65 72 20 70 6f 69 6e 74 65 64 20 74 6f  teger pointed to
98e0: 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
98f0: 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 2e 20   database size. 
9900: 20 54 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   The integer.** 
9910: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 73 65  pointed to is se
9920: 74 20 74 6f 20 74 68 65 20 6e 65 77 20 6c 69 6d  t to the new lim
9930: 69 74 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  it..**.** <li>[[
9940: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
9950: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
9960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
9970: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
9980: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
9990: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
99a0: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
99b0: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
99c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
99d0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
99e0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
99f0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
9a00: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
9a10: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
9a20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
9a30: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
9a40: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
9a50: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
9a60: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
9a70: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
9a80: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
9a90: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
9aa0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
9ab0: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
9ac0: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
9ad0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
9ae0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
9af0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
9b00: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
9b10: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
9b20: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
9b30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b40: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9b50: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9b60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9b70: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
9b80: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
9b90: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9ba0: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9bb0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9bc0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
9bd0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9be0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9bf0: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9c00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
9c10: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a  NAL_POINTER]..**
9c20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9c30: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9c40: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9c50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
9c60: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f  URNAL_POINTER] o
9c70: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9c80: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9c90: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9ca0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9cb0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9cc0: 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69  h the journal fi
9cd0: 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68  le (either.** th
9ce0: 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  e [rollback jour
9cf0: 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69  nal] or the [wri
9d00: 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66  te-ahead log]) f
9d10: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
9d20: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9d30: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9d40: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9d50: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  FILE_POINTER]..*
9d60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9d70: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9d80: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9d90: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9da0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9db0: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
9dc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9dd0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
9de0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9df0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
9e00: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
9e10: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9e20: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
9e30: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
9e40: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
9e50: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
9e60: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
9e70: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
9e80: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9e90: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9ea0: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
9eb0: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
9ec0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
9ed0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
9ee0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
9ef0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
9f00: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
9f10: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9f20: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
9f30: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
9f40: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
9f50: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
9f60: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
9f70: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
9f80: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9f90: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9fa0: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
9fb0: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
9fc0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
9fd0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
9fe0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
9ff0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
a000: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
a010: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
a020: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
a030: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
a040: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
a050: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
a060: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
a070: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
a080: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
a090: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
a0a0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a0b0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
a0c0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
a0d0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
a0e0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
a0f0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
a100: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
a110: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
a120: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a130: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
a140: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
a150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
a160: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
a170: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
a180: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
a190: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
a1a0: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
a1b0: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
a1c0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
a1d0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
a1e0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
a1f0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
a200: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
a210: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
a220: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
a230: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
a240: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
a250: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
a260: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
a270: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a280: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
a290: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
a2a0: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
a2b0: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
a2c0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
a2d0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
a2e0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
a2f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
a300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
a310: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
a320: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a330: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
a340: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
a350: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
a360: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
a370: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
a380: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
a390: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
a3a0: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
a3b0: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
a3c0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
a3d0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
a3e0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
a3f0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
a400: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
a410: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
a420: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
a430: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
a440: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
a450: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
a460: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
a470: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
a480: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
a490: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
a4a0: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
a4b0: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
a4c0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
a4d0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
a4e0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
a4f0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
a500: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
a510: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
a520: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
a530: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
a540: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
a550: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
a560: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
a570: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
a580: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
a590: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
a5a0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
a5b0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
a5c0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
a5d0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
a5e0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
a5f0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
a600: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
a610: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e  integer is the n
a620: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
a630: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
a640: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
a650: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
a660: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
a670: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
a680: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
a690: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
a6a0: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
a6b0: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
a6c0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
a6d0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
a6e0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
a6f0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
a700: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
a710: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
a720: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
a730: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
a740: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
a750: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a760: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
a770: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a780: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
a790: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a7a0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a7b0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a7c0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
a7d0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
a7e0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
a7f0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
a800: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
a810: 67 20 28 5b 57 41 4c 20 66 69 6c 65 5d 29 20 61  g ([WAL file]) a
a820: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a830: 0a 2a 2a 20 66 69 6c 65 73 20 75 73 65 64 20 66  .** files used f
a840: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
a850: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
a860: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
a870: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
a880: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
a890: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
a8a0: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
a8b0: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
a8c0: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
a8d0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
a8e0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
a8f0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
a900: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
a910: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
a920: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
a930: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
a940: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
a950: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
a960: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
a970: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
a980: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
a990: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
a9a0: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
a9b0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a9c0: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
a9d0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
a9e0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
a9f0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
aa00: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
aa10: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
aa20: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
aa30: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
aa40: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
aa50: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
aa60: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
aa70: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
aa80: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
aa90: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
aaa0: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
aab0: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
aac0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
aad0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
aae0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
aaf0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ab00: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
ab10: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
ab20: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab30: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
ab40: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
ab50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
ab60: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
ab70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
ab80: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
ab90: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
aba0: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
abb0: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
abc0: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
abd0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
abe0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
abf0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
ac00: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
ac10: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
ac20: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
ac30: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
ac40: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
ac50: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
ac60: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
ac70: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
ac80: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
ac90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
aca0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
acb0: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
acc0: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
acd0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
ace0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
acf0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
ad00: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
ad10: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
ad20: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
ad30: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
ad40: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
ad50: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
ad60: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ad70: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
ad80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ad90: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
ada0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
adb0: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
adc0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
add0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
ade0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
adf0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
ae00: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
ae10: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
ae20: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
ae30: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
ae40: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
ae50: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
ae60: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
ae70: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
ae80: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
ae90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
aea0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aeb0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
aec0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
aed0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
aee0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
aef0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
af00: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
af10: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
af20: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
af30: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
af40: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
af50: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
af60: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
af70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
af80: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
af90: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
afa0: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
afb0: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
afc0: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
afd0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
afe0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
aff0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
b000: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
b010: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
b020: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
b030: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
b040: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
b050: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
b060: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
b070: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
b080: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
b090: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
b0a0: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
b0b0: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
b0c0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
b0d0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
b0e0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
b0f0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
b100: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
b110: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
b120: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
b130: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
b140: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
b150: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
b160: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b170: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
b180: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
b190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
b1a0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66  OINTER] opcode f
b1b0: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74  inds a pointer t
b1c0: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a  o the top-level.
b1d0: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65  ** [VFSes] curre
b1e0: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28  ntly in use.  ^(
b1f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69  The argument X i
b200: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c  n.** sqlite3_fil
b210: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c  e_control(db,SQL
b220: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
b230: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65  INTER,X) must be
b240: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71  .** of type "[sq
b250: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20  lite3_vfs] **". 
b260: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69   This opcodes wi
b270: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20  ll set *X.** to 
b280: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
b290: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29   top-level VFS.)
b2a0: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65  ^.** ^When there
b2b0: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46   are multiple VF
b2c0: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73  S shims in the s
b2d0: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64  tack, this opcod
b2e0: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75  e finds the.** u
b2f0: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f  pper-most shim o
b300: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
b310: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b320: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
b330: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
b340: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
b350: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
b360: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
b370: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b380: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
b390: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
b3a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
b3b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
b3c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
b3d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
b3e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
b3f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
b400: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
b410: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b420: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b430: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
b440: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
b450: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
b460: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
b470: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
b480: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
b490: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
b4a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
b4b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
b4c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
b4d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
b4e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
b4f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
b500: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
b510: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
b520: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b530: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
b540: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
b550: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
b560: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
b570: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
b580: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
b590: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b5a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
b5b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
b5c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
b5d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
b5e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
b5f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
b600: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
b610: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
b620: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
b630: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
b640: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b650: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b660: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
b670: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
b680: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
b690: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
b6a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b6b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
b6c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
b6d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
b6e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
b6f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
b700: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
b710: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
b720: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
b730: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
b740: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
b750: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
b760: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
b770: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
b780: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
b790: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
b7a0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
b7b0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
b7c0: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
b7d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b7e0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
b7f0: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
b800: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
b810: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
b820: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
b830: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
b840: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
b850: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
b860: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
b870: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
b880: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
b890: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
b8a0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
b8b0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
b8c0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
b8d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b8e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
b8f0: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
b900: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
b910: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
b920: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
b930: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
b940: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
b950: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
b960: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b970: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b980: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
b990: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b9a0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
b9b0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
b9c0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
b9d0: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
b9e0: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
b9f0: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ba00: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ba10: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ba20: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ba30: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ba40: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ba50: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
ba60: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ba70: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
ba80: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ba90: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
baa0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
bab0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
bac0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
bad0: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
bae0: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
baf0: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
bb00: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
bb10: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
bb20: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
bb30: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
bb40: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
bb50: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
bb60: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
bb70: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
bb80: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
bb90: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
bba0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
bbb0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
bbc0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
bbd0: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
bbe0: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
bbf0: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
bc00: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
bc10: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
bc20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bc30: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
bc40: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
bc50: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
bc60: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
bc70: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
bc80: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
bc90: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
bca0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
bcb0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
bcc0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
bcd0: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
bce0: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
bcf0: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
bd00: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
bd10: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
bd20: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
bd30: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
bd40: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
bd50: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
bd60: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
bd70: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
bd80: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
bd90: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
bda0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
bdb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
bdc0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
bdd0: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
bde0: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
bdf0: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
be00: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
be10: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
be20: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
be30: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
be40: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
be50: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
be60: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
be70: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
be80: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
be90: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
bea0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
beb0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
bec0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
bed0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
bee0: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
bef0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
bf00: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
bf10: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
bf20: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
bf30: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
bf40: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
bf50: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
bf60: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
bf70: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
bf80: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
bf90: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
bfa0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
bfb0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
bfc0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
bfd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
bfe0: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
bff0: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
c000: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
c010: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
c020: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
c030: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
c040: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
c050: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
c060: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
c070: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c080: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
c090: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c0a0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
c0b0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
c0c0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
c0d0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
c0e0: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
c0f0: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
c100: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
c110: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
c120: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
c130: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
c140: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
c150: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
c160: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
c170: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
c180: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
c190: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
c1a0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
c1b0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
c1c0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
c1d0: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
c1e0: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
c1f0: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
c200: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
c210: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
c220: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
c230: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
c240: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
c250: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
c260: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
c270: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
c280: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
c290: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
c2a0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
c2b0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
c2c0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
c2d0: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
c2e0: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
c2f0: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
c300: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
c310: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
c320: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
c330: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
c340: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c350: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c360: 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  GET_HANDLE]].** 
c370: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c380: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
c390: 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  LE] opcode can b
c3a0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
c3b0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
c3c0: 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68  ng native file h
c3d0: 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64  andle associated
c3e0: 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e   with a file han
c3f0: 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a  dle.  This file.
c400: 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  ** control inter
c410: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
c420: 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20  nt as a pointer 
c430: 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65  to a native file
c440: 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77   handle and.** w
c450: 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74  rites the result
c460: 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e  ing value there.
c470: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c480: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c490: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
c4a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c4b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
c4c0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
c4d0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
c4e0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
c4f0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
c500: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
c510: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
c520: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
c530: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
c540: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
c550: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
c560: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
c570: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
c580: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
c590: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
c5a0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
c5b0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
c5c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c5d0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c5e0: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
c600: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
c610: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
c620: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
c630: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
c640: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
c650: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
c660: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
c670: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
c680: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
c690: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
c6a0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
c6b0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
c6c0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
c6d0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
c6e0: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
c6f0: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
c700: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
c710: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
c720: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
c730: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
c740: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c750: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
c760: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c770: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
c780: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
c790: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
c7a0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
c7b0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
c7c0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c7d0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
c7e0: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
c7f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
c800: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
c810: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
c820: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
c830: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
c840: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
c850: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
c860: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
c870: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
c880: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c890: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
c8a0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a  is opcode.  .**.
c8b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c8c0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
c8d0: 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66  IC_WRITE]].** If
c8e0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
c8f0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
c900: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65  WRITE] opcode re
c910: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c  turns SQLITE_OK,
c920: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c   then.** the fil
c930: 65 20 64 65 73 63 72 69 70 74 6f 72 20 69 73 20  e descriptor is 
c940: 70 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63 68  placed in "batch
c950: 20 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68   write mode", wh
c960: 69 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c  ich.** means all
c970: 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74   subsequent writ
c980: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c  e operations wil
c990: 6c 20 62 65 20 64 65 66 65 72 72 65 64 20 61 6e  l be deferred an
c9a0: 64 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63  d done.** atomic
c9b0: 61 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74  ally at the next
c9c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
c9d0: 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49  OMMIT_ATOMIC_WRI
c9e0: 54 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a  TE].  Systems.**
c9f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70   that do not sup
ca00: 70 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69  port batch atomi
ca10: 63 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65  c writes will re
ca20: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
ca30: 4f 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77  OUND..** ^Follow
ca40: 69 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c  ing a successful
ca50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45   SQLITE_FCNTL_BE
ca60: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
ca70: 20 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a   and prior to.**
ca80: 20 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51   the closing [SQ
ca90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
caa0: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  T_ATOMIC_WRITE] 
cab0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  or.** [SQLITE_FC
cac0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
cad0: 4d 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69  MIC_WRITE], SQLi
cae0: 74 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20  te will make.** 
caf0: 6e 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  no VFS interface
cb00: 20 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61   calls on the sa
cb10: 6d 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  me [sqlite3_file
cb20: 5d 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  ] file descripto
cb30: 72 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20  r.** except for 
cb40: 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72  calls to the xWr
cb50: 69 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74  ite method and t
cb60: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
cb70: 6d 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b  method.** with [
cb80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
cb90: 45 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  E_HINT]..**.** <
cba0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
cbb0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
cbc0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  WRITE]].** The [
cbd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
cbe0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
cbf0: 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  ] opcode causes 
cc00: 61 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65  all write.** ope
cc10: 72 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68  rations since th
cc20: 65 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65  e previous succe
cc30: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a  ssful call to .*
cc40: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
cc50: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
cc60: 54 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72  TE] to be perfor
cc70: 6d 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a  med atomically..
cc80: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
cc90: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
cca0: 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20  LITE_OK] if and 
ccb0: 6f 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69 74  only if the writ
ccc0: 65 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70  es were.** all p
ccd0: 65 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73  erformed success
cce0: 66 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62  fully and have b
ccf0: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f  een committed to
cd00: 20 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72   persistent stor
cd10: 61 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  age..** ^Regardl
cd20: 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
cd30: 72 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63  r not it is succ
cd40: 65 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c  essful, this fil
cd50: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a  e control takes.
cd60: 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63  ** the file desc
cd70: 72 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61  riptor out of ba
cd80: 74 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73  tch write mode s
cd90: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cda0: 71 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f  quent.** write o
cdb0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e  perations are in
cdc0: 64 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53  dependent..** ^S
cdd0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
cde0: 20 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46   invoke SQLITE_F
cdf0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d  CNTL_COMMIT_ATOM
ce00: 49 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74  IC_WRITE without
ce10: 0a 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63  .** a prior succ
ce20: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
ce30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
ce40: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
ce50: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
ce70: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
ce80: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
ce90: 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b  E_FCNTL_ROLLBACK
cea0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f  _ATOMIC_WRITE] o
ceb0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c  pcode causes all
cec0: 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74   write.** operat
ced0: 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70  ions since the p
cee0: 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66  revious successf
cef0: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b  ul call to .** [
cf00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
cf10: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
cf20: 20 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61   to be rolled ba
cf30: 63 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c  ck..** ^This fil
cf40: 65 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20  e control takes 
cf50: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
cf60: 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68  tor out of batch
cf70: 20 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73   write mode.** s
cf80: 6f 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65  o that all subse
cf90: 71 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72  quent write oper
cfa0: 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70  ations are indep
cfb0: 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69  endent..** ^SQLi
cfc0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
cfd0: 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  voke SQLITE_FCNT
cfe0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
cff0: 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a  C_WRITE without.
d000: 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  ** a prior succe
d010: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53  ssful call to [S
d020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
d030: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  N_ATOMIC_WRITE].
d040: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d050: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54  ITE_FCNTL_LOCK_T
d060: 49 4d 45 4f 55 54 5d 5d 0a 2a 2a 20 54 68 65 20  IMEOUT]].** The 
d070: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
d080: 43 4b 5f 54 49 4d 45 4f 55 54 5d 20 6f 70 63 6f  CK_TIMEOUT] opco
d090: 64 65 20 63 61 75 73 65 73 20 61 74 74 65 6d 70  de causes attemp
d0a0: 74 73 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ts to obtain.** 
d0b0: 61 20 66 69 6c 65 20 6c 6f 63 6b 20 75 73 69 6e  a file lock usin
d0c0: 67 20 74 68 65 20 78 4c 6f 63 6b 20 6f 72 20 78  g the xLock or x
d0d0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 73 20  ShmLock methods 
d0e0: 6f 66 20 74 68 65 20 56 46 53 20 74 6f 20 77 61  of the VFS to wa
d0f0: 69 74 0a 2a 2a 20 66 6f 72 20 75 70 20 74 6f 20  it.** for up to 
d100: 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  M milliseconds b
d110: 65 66 6f 72 65 20 66 61 69 6c 69 6e 67 2c 20 77  efore failing, w
d120: 68 65 72 65 20 4d 20 69 73 20 74 68 65 20 73 69  here M is the si
d130: 6e 67 6c 65 20 0a 2a 2a 20 75 6e 73 69 67 6e 65  ngle .** unsigne
d140: 64 20 69 6e 74 65 67 65 72 20 70 61 72 61 6d 65  d integer parame
d150: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
d160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41  [SQLITE_FCNTL_DA
d170: 54 41 5f 56 45 52 53 49 4f 4e 5d 5d 0a 2a 2a 20  TA_VERSION]].** 
d180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d190: 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 5d 20  L_DATA_VERSION] 
d1a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
d1b0: 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73  o detect changes
d1c0: 20 74 6f 0a 2a 2a 20 61 20 64 61 74 61 62 61 73   to.** a databas
d1d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 61 72 67  e file.  The arg
d1e0: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
d1f0: 65 72 20 74 6f 20 61 20 33 32 2d 62 69 74 20 75  er to a 32-bit u
d200: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e  nsigned integer.
d210: 0a 2a 2a 20 54 68 65 20 22 64 61 74 61 20 76 65  .** The "data ve
d220: 72 73 69 6f 6e 22 20 66 6f 72 20 74 68 65 20 70  rsion" for the p
d230: 61 67 65 72 20 69 73 20 77 72 69 74 74 65 6e 20  ager is written 
d240: 69 6e 74 6f 20 74 68 65 20 70 6f 69 6e 74 65 72  into the pointer
d250: 2e 20 20 54 68 65 0a 2a 2a 20 22 64 61 74 61 20  .  The.** "data 
d260: 76 65 72 73 69 6f 6e 22 20 63 68 61 6e 67 65 73  version" changes
d270: 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 63 68   whenever any ch
d280: 61 6e 67 65 20 6f 63 63 75 72 73 20 74 6f 20 74  ange occurs to t
d290: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
d2a0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
d2b0: 65 2c 20 65 69 74 68 65 72 20 74 68 72 6f 75 67  e, either throug
d2c0: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  h SQL statements
d2d0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
d2e0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
d2f0: 69 6f 6e 20 6f 72 20 74 68 72 6f 75 67 68 20 74  ion or through t
d300: 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 6f 6d 6d  ransactions comm
d310: 69 74 74 65 64 20 62 79 20 73 65 70 61 72 61 74  itted by separat
d320: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
d330: 6e 6e 65 63 74 69 6f 6e 73 20 70 6f 73 73 69 62  nnections possib
d340: 6c 79 20 69 6e 20 6f 74 68 65 72 20 70 72 6f 63  ly in other proc
d350: 65 73 73 65 73 2e 20 54 68 65 20 5b 73 71 6c 69  esses. The [sqli
d360: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
d370: 73 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  s()].** interfac
d380: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
d390: 20 66 69 6e 64 20 69 66 20 61 6e 79 20 64 61 74   find if any dat
d3a0: 61 62 61 73 65 20 6f 6e 20 74 68 65 20 63 6f 6e  abase on the con
d3b0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 63 68 61 6e  nection has chan
d3c0: 67 65 64 2c 0a 2a 2a 20 62 75 74 20 74 68 61 74  ged,.** but that
d3d0: 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 70 6f   interface respo
d3e0: 6e 64 73 20 74 6f 20 63 68 61 6e 67 65 73 20 6f  nds to changes o
d3f0: 6e 20 54 45 4d 50 20 61 73 20 77 65 6c 6c 20 61  n TEMP as well a
d400: 73 20 4d 41 49 4e 20 61 6e 64 20 64 6f 65 73 0a  s MAIN and does.
d410: 2a 2a 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  ** not provide a
d420: 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65   mechanism to de
d430: 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 20  tect changes to 
d440: 4d 41 49 4e 20 6f 6e 6c 79 2e 20 20 41 6c 73 6f  MAIN only.  Also
d450: 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
d460: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d470: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
d480: 70 6f 6e 64 73 20 74 6f 20 69 6e 74 65 72 6e 61  ponds to interna
d490: 6c 20 63 68 61 6e 67 65 73 20 6f 6e 6c 79 20 61  l changes only a
d4a0: 6e 64 0a 2a 2a 20 6f 6d 69 74 73 20 63 68 61 6e  nd.** omits chan
d4b0: 67 65 73 20 6d 61 64 65 20 62 79 20 6f 74 68 65  ges made by othe
d4c0: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
d4d0: 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
d4e0: 5b 50 52 41 47 4d 41 20 64 61 74 61 5f 76 65 72  [PRAGMA data_ver
d4f0: 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64 20 70 72  sion] command pr
d500: 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e 69 73  ovide a mechanis
d510: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d520: 67 65 73 20 74 6f 0a 2a 2a 20 61 20 73 69 6e 67  ges to.** a sing
d530: 6c 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  le attached data
d540: 62 61 73 65 20 74 68 61 74 20 6f 63 63 75 72 20  base that occur 
d550: 64 75 65 20 74 6f 20 6f 74 68 65 72 20 64 61 74  due to other dat
d560: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d570: 73 2c 0a 2a 2a 20 62 75 74 20 6f 6d 69 74 73 20  s,.** but omits 
d580: 63 68 61 6e 67 65 73 20 69 6d 70 6c 65 6d 65 6e  changes implemen
d590: 74 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  ted by the datab
d5a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
d5b0: 6e 20 77 68 69 63 68 20 69 74 20 69 73 0a 2a 2a  n which it is.**
d5c0: 20 63 61 6c 6c 65 64 2e 20 20 54 68 69 73 20 66   called.  This f
d5d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 74  ile control is t
d5e0: 68 65 20 6f 6e 6c 79 20 6d 65 63 68 61 6e 69 73  he only mechanis
d5f0: 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 61 6e  m to detect chan
d600: 67 65 73 20 74 68 61 74 0a 2a 2a 20 68 61 70 70  ges that.** happ
d610: 65 6e 20 65 69 74 68 65 72 20 69 6e 74 65 72 6e  en either intern
d620: 61 6c 6c 79 20 6f 72 20 65 78 74 65 72 6e 61 6c  ally or external
d630: 6c 79 20 61 6e 64 20 74 68 61 74 20 61 72 65 20  ly and that are 
d640: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
d650: 2a 2a 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ** a particular 
d660: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
d670: 65 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  e..** </ul>.*/.#
d680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d690: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
d6a0: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
d6b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d6c0: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
d6d0: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
d6e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d6f0: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
d700: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
d710: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d720: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
d730: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
d740: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d750: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
d760: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
d770: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d780: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
d790: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
d7a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
d7b0: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
d7c0: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
d7d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
d7e0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
d7f0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
d800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d810: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
d820: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
d830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
d840: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
d850: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
d860: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
d870: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
d880: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
d890: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
d8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d8b0: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
d8c0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
d8d0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
d8e0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
d8f0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
d900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
d910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d920: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
d930: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
d940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d950: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
d960: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
d970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d980: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
d990: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
d9a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d9b0: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
d9c0: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
d9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d9e0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
d9f0: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
da00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
da10: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
da20: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
da30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
da40: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
da50: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
da60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
da70: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
da80: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
da90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
daa0: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
dab0: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20       24.#define 
dac0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
dad0: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20  VFS             
dae0: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53      25.#define S
daf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20  QLITE_FCNTL_RBU 
db00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
db10: 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51     26.#define SQ
db20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
db30: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
db40: 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c    27.#define SQL
db50: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
db60: 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  L_POINTER       
db70: 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   28.#define SQLI
db80: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
db90: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
dba0: 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  29.#define SQLIT
dbb0: 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20  E_FCNTL_PDB     
dbc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
dbd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
dbe0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
dbf0: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 20 33 31  MIC_WRITE     31
dc00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc10: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
dc20: 4d 49 43 5f 57 52 49 54 45 20 20 20 20 33 32 0a  MIC_WRITE    32.
dc30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dc40: 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54  CNTL_ROLLBACK_AT
dc50: 4f 4d 49 43 5f 57 52 49 54 45 20 20 33 33 0a 23  OMIC_WRITE  33.#
dc60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dc70: 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54  NTL_LOCK_TIMEOUT
dc80: 20 20 20 20 20 20 20 20 20 20 20 33 34 0a 23 64             34.#d
dc90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dca0: 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f 4e 20  TL_DATA_VERSION 
dcb0: 20 20 20 20 20 20 20 20 20 20 33 35 0a 23 64 65            35.#de
dcc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dcd0: 4c 5f 53 49 5a 45 5f 4c 49 4d 49 54 20 20 20 20  L_SIZE_LIMIT    
dce0: 20 20 20 20 20 20 20 20 20 33 36 0a 0a 2f 2a 20           36../* 
dcf0: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73  deprecated names
dd00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dd10: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
dd20: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
dd30: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
dd40: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
dd50: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
dd60: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
dd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
dd80: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
dd90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
dda0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
ddb0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
ddc0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a  _LAST_ERRNO.../*
ddd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
dde0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
ddf0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
de00: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
de10: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
de20: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
de30: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
de40: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
de50: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
de60: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
de70: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
de80: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
de90: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
dea0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
deb0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
dec0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
ded0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
dee0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
def0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
df00: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
df10: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
df20: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
df30: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
df40: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
df50: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
df60: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  EF: Loadable Ext
df70: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a  ension Thunk.**.
df80: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
df90: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74  the opaque sqlit
dfa0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
dfb0: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73  structure is pas
dfc0: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68  sed as.** the th
dfd0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
dfe0: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66   entry points of
dff0: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e   [loadable exten
e000: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a  sions].  This.**
e010: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
e020: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20  be typedefed in 
e030: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72  order to work ar
e040: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61  ound compiler wa
e050: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d  rnings.** on som
e060: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a  e platforms..*/.
e070: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
e080: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
e090: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  nes sqlite3_api_
e0a0: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a  routines;../*.**
e0b0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
e0c0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
e0d0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
e0e0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
e0f0: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
e100: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
e110: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
e120: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
e130: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
e140: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
e150: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
e160: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
e170: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
e180: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
e190: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
e1a0: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
e1b0: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
e1c0: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
e1d0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
e1e0: 54 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63  The VFS interfac
e1f0: 65 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65  e is sometimes e
e200: 78 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e  xtended by addin
e210: 67 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e  g new methods on
e220: 74 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20  to.** the end.  
e230: 45 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61  Each time such a
e240: 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75  n extension occu
e250: 72 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e  rs, the iVersion
e260: 20 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63   field.** is inc
e270: 72 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69  remented.  The i
e280: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74  Version value st
e290: 61 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69  arted out as 1 i
e2a0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72  n.** SQLite [ver
e2b0: 73 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b  sion 3.5.0] on [
e2c0: 64 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74  dateof:3.5.0], t
e2d0: 68 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f  hen increased to
e2e0: 20 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74   2.** with SQLit
e2f0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30  e [version 3.7.0
e300: 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37  ] on [dateof:3.7
e310: 2e 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e  .0], and then in
e320: 63 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20  creased.** to 3 
e330: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72  with SQLite [ver
e340: 73 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b  sion 3.7.6] on [
e350: 64 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20  dateof:3.7.6].  
e360: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
e370: 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65  s.** may be appe
e380: 6e 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69  nded to the sqli
e390: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61  te3_vfs object a
e3a0: 6e 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  nd the iVersion 
e3b0: 76 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63  value.** may inc
e3c0: 72 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66  rease again in f
e3d0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
e3e0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74  f SQLite..** Not
e3f0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
e400: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
e410: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
e420: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
e430: 20 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d   transition from
e440: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
e450: 69 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76  ion 3.5.9] to [v
e460: 65 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e  ersion 3.6.0] on
e470: 20 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a   [dateof:3.6.0].
e480: 2a 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  ** and yet the i
e490: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
e4a0: 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a  s not modified..
e4b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
e4c0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
e4d0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
e4e0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
e4f0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
e500: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
e510: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
e520: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
e530: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
e540: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
e550: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
e560: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
e570: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
e580: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
e590: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
e5a0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
e5b0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
e5c0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
e5d0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
e5e0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
e5f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
e600: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
e610: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
e620: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
e630: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
e640: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
e650: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
e660: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
e670: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
e680: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
e690: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
e6a0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
e6b0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
e6c0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
e6d0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
e6e0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
e6f0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
e700: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
e710: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
e720: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
e730: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
e740: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
e750: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
e760: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
e770: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
e780: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e790: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
e7a0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
e7b0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
e7c0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
e7d0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
e7e0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
e7f0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
e800: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
e810: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
e820: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
e830: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
e840: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
e850: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
e860: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
e870: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
e880: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
e890: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
e8a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
e8b0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
e8c0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
e8d0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
e8e0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
e8f0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
e900: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
e910: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
e920: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
e930: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
e940: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e950: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
e960: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
e970: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
e980: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
e990: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
e9a0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
e9b0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
e9c0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
e9d0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
e9e0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
e9f0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
ea00: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
ea10: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
ea20: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
ea30: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
ea40: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
ea50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ea60: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
ea70: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
ea80: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
ea90: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
eaa0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
eab0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
eac0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
ead0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
eae0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
eaf0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
eb00: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
eb10: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
eb20: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
eb30: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
eb40: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
eb50: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
eb60: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
eb70: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
eb80: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
eb90: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
eba0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
ebb0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
ebc0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
ebd0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
ebe0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
ebf0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
ec00: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
ec10: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
ec20: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
ec30: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
ec40: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ec50: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
ec60: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
ec70: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
ec80: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
ec90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
eca0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
ecb0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
ecc0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
ecd0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
ece0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
ecf0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
ed00: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
ed10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ed20: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
ed30: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
ed40: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
ed50: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
ed60: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ed70: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
ed80: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ed90: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
eda0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
edb0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
edc0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
edd0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ede0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
edf0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ee00: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
ee10: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ee20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
ee30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ee40: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
ee50: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ee60: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
ee70: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
ee80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
ee90: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
eea0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
eeb0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
eec0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
eed0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
eee0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
eef0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
ef00: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
ef10: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
ef20: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
ef30: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
ef40: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
ef50: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
ef60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ef70: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
ef80: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
ef90: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
efa0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
efb0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
efc0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
efd0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
efe0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
eff0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
f000: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
f010: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
f020: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
f030: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
f040: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
f050: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f060: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
f070: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
f080: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
f090: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
f0a0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
f0b0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
f0c0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
f0d0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
f0e0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
f0f0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
f100: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
f110: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
f120: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
f130: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
f140: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f150: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
f160: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f170: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
f180: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
f190: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
f1a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
f1b0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
f1c0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
f1d0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
f1e0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
f1f0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
f200: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
f210: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
f220: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
f230: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
f240: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
f250: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
f260: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
f270: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
f280: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
f290: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
f2a0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
f2b0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
f2c0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
f2d0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f2e0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
f2f0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
f300: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
f310: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
f320: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
f330: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
f340: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
f350: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
f360: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
f370: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
f380: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
f390: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
f3a0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
f3b0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
f3c0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
f3d0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
f3e0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
f3f0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
f400: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
f410: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
f420: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
f430: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
f440: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
f450: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
f460: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
f470: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
f480: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
f490: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
f4a0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
f4b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
f4c0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
f4d0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
f4e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
f4f0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
f500: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
f510: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
f520: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
f530: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
f540: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
f550: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
f560: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
f570: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
f580: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
f590: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
f5a0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
f5b0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
f5c0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
f5d0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
f5e0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
f5f0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
f600: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
f610: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
f620: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
f630: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
f640: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
f650: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
f660: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
f670: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
f680: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
f690: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
f6a0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
f6b0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
f6c0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
f6d0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
f6e0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
f6f0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
f700: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
f710: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
f720: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f730: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
f740: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
f750: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
f760: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
f770: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f780: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
f790: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
f7a0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
f7b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
f7c0: 43 45 53 53 5f 52 45 41 44 0a 2a 2a 20 66 6c 61  CESS_READ.** fla
f7d0: 67 20 69 73 20 6e 65 76 65 72 20 61 63 74 75 61  g is never actua
f7e0: 6c 6c 79 20 75 73 65 64 20 61 6e 64 20 69 73 20  lly used and is 
f7f0: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
f800: 69 6e 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  in the built-in.
f810: 2a 2a 20 56 46 53 65 73 20 6f 66 20 53 51 4c 69  ** VFSes of SQLi
f820: 74 65 2e 20 20 54 68 65 20 66 69 6c 65 20 69 73  te.  The file is
f830: 20 6e 61 6d 65 64 20 62 79 20 74 68 65 20 73 65   named by the se
f840: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 61 6e  cond argument an
f850: 64 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  d can be a.** di
f860: 72 65 63 74 6f 72 79 2e 20 54 68 65 20 78 41 63  rectory. The xAc
f870: 63 65 73 73 20 6d 65 74 68 6f 64 20 72 65 74 75  cess method retu
f880: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
f890: 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 73 6f  on success or so
f8a0: 6d 65 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 65  me.** non-zero e
f8b0: 72 72 6f 72 20 63 6f 64 65 20 69 66 20 74 68 65  rror code if the
f8c0: 72 65 20 69 73 20 61 6e 20 49 2f 4f 20 65 72 72  re is an I/O err
f8d0: 6f 72 20 6f 72 20 69 66 20 74 68 65 20 6e 61 6d  or or if the nam
f8e0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 69 6c 65  e of.** the file
f8f0: 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 73 65   given in the se
f900: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
f910: 20 69 6c 6c 65 67 61 6c 2e 20 20 49 66 20 53 51   illegal.  If SQ
f920: 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 69 73 20 72 65  LITE_OK.** is re
f930: 74 75 72 6e 65 64 2c 20 74 68 65 6e 20 6e 6f 6e  turned, then non
f940: 2d 7a 65 72 6f 20 6f 72 20 7a 65 72 6f 20 69 73  -zero or zero is
f950: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
f960: 52 65 73 4f 75 74 20 74 6f 20 69 6e 64 69 63 61  ResOut to indica
f970: 74 65 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  te.** whether or
f980: 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 69 73   not the file is
f990: 20 61 63 63 65 73 73 69 62 6c 65 2e 20 20 0a 2a   accessible.  .*
f9a0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
f9b0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
f9c0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
f9d0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
f9e0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
f9f0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
fa00: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
fa10: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
fa20: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
fa30: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
fa40: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
fa50: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
fa60: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
fa70: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
fa80: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
fa90: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
faa0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
fab0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
fac0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
fad0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
fae0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
faf0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
fb00: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
fb10: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
fb20: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
fb30: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
fb40: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
fb50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
fb60: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
fb70: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
fb80: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
fb90: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
fba0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
fbb0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
fbc0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
fbd0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
fbe0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
fbf0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
fc00: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
fc10: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
fc20: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
fc30: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
fc40: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
fc50: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
fc60: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
fc70: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
fc80: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
fc90: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
fca0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
fcb0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
fcc0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
fcd0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
fce0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
fcf0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
fd00: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
fd10: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
fd20: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
fd30: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
fd40: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
fd50: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
fd60: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
fd70: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
fd80: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
fd90: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
fda0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
fdb0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
fdc0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
fdd0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
fde0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
fdf0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
fe00: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
fe10: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
fe20: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
fe30: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
fe40: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
fe50: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
fe60: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
fe70: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
fe80: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
fe90: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
fea0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
feb0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
fec0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
fed0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
fee0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
fef0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
ff00: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
ff10: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
ff20: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
ff30: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ff40: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
ff50: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
ff60: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
ff70: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
ff80: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
ff90: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
ffa0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
ffb0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
ffc0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
ffd0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
ffe0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
fff0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
10000 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
10010 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
10020 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
10030 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
10040 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
10050 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
10060 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
10070 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
10080 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
10090 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
100a0 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
100b0 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
100c0 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
100d0 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
100e0 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
100f0 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
10100 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
10110 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
10120 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
10130 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
10140 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
10150 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
10160 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
10170 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
10180 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
10190 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
101a0 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
101b0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
101c0 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
101d0 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
101e0 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
101f0 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
10200 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
10210 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
10220 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
10230 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
10240 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
10250 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
10260 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
10270 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
10280 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
10290 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
102a0 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
102b0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
102c0 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
102d0 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
102e0 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
102f0 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
10300 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
10310 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
10320 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
10330 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
10340 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
10350 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
10360 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
10370 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
10380 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
10390 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
103a0 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
103b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
103c0 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
103d0 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
103e0 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
103f0 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
10400 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
10410 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
10420 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
10430 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
10440 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
10450 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
10460 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
10470 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
10480 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10490 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
104a0 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
104b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
104c0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
104d0 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
104e0 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
104f0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10500 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
10510 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
10520 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
10530 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
10540 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
10550 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
10560 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
10570 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
10580 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
10590 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
105a0 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
105b0 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
105c0 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
105d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
105e0 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
105f0 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
10600 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
10610 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
10620 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
10630 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
10640 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
10650 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
10660 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
10670 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
10680 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
10690 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
106a0 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
106b0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
106c0 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
106d0 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
106e0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
106f0 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
10700 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
10710 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
10720 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
10730 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
10740 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
10750 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
10760 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
10770 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
10780 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
10790 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
107a0 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
107b0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
107c0 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
107d0 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
107e0 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
107f0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
10800 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
10810 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
10820 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
10830 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
10840 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
10850 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
10860 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
10870 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
10880 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
10890 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
108a0 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
108b0 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
108c0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
108d0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
108e0 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
108f0 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
10900 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
10910 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
10920 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
10930 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
10940 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
10950 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
10960 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
10970 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10980 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
10990 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
109a0 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
109b0 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
109c0 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
109d0 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
109e0 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
109f0 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
10a00 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
10a10 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
10a20 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
10a30 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
10a40 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
10a50 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
10a60 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
10a70 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
10a80 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
10a90 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
10aa0 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
10ab0 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
10ac0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
10ad0 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
10ae0 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
10af0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
10b00 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
10b10 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
10b20 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
10b30 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
10b40 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
10b50 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
10b60 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
10b70 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10b80 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
10b90 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
10ba0 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
10bb0 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
10bc0 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
10bd0 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
10be0 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
10bf0 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
10c00 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
10c10 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
10c20 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
10c30 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
10c40 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
10c50 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
10c60 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
10c70 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
10c80 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
10c90 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
10ca0 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
10cb0 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
10cc0 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
10cd0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
10ce0 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
10cf0 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
10d00 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
10d10 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
10d20 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
10d30 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
10d40 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
10d50 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
10d60 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
10d70 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
10d80 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
10d90 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
10da0 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
10db0 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
10dc0 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
10dd0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
10de0 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
10df0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
10e00 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
10e10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10e20 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
10e30 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
10e40 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
10e50 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
10e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
10e70 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
10e80 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
10e90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10ea0 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
10eb0 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
10ec0 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
10ed0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
10ee0 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
10ef0 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
10f00 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
10f10 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
10f20 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
10f30 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
10f40 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
10f50 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
10f60 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
10f70 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
10f80 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
10f90 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
10fa0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
10fb0 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
10fc0 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
10fd0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
10fe0 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
10ff0 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
11000 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
11010 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
11020 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
11030 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
11040 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
11050 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
11060 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
11070 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
11080 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
11090 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
110a0 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
110b0 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
110c0 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
110d0 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
110e0 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
110f0 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
11100 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
11110 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
11120 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
11130 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
11140 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
11150 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
11160 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
11170 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
11180 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
11190 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
111a0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
111b0 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
111c0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
111d0 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
111e0 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
111f0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
11200 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
11210 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
11220 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
11230 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
11240 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
11250 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
11260 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
11270 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
11280 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
11290 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
112a0 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
112b0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
112c0 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
112d0 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
112e0 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
112f0 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
11300 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
11310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
11320 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
11330 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
11340 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
11350 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
11360 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
11370 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11380 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
11390 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
113a0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
113b0 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
113c0 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
113d0 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
113e0 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
113f0 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
11400 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
11410 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
11420 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
11430 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
11440 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
11450 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
11460 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
11470 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
11480 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
11490 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
114a0 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
114b0 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
114c0 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
114d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
114e0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
114f0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11500 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
11510 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
11520 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
11530 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
11540 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
11550 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
11560 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
11570 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
11580 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
11590 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
115a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
115b0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
115c0 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
115d0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
115e0 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
115f0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
11600 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
11610 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
11620 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
11630 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
11640 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
11650 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
11660 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
11670 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
11680 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
11690 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
116a0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
116b0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
116c0 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
116d0 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
116e0 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
116f0 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
11700 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
11710 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
11720 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
11730 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
11740 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
11750 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
11760 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
11770 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
11780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11790 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
117a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
117b0 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
117c0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
117d0 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
117e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
117f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
11800 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
11810 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
11820 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
11830 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
11840 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
11850 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
11860 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
11870 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
11880 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
11890 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
118a0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
118b0 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
118c0 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
118d0 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
118e0 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
118f0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
11900 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
11910 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
11920 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
11930 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
11940 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
11950 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
11960 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
11970 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
11980 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
11990 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
119a0 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
119b0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
119c0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
119d0 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
119e0 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
119f0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
11a00 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
11a10 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
11a20 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
11a30 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
11a40 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
11a50 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
11a60 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
11a70 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11a80 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
11a90 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
11aa0 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
11ab0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11ac0 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
11ad0 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
11ae0 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
11af0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
11b00 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11b10 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
11b20 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
11b30 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
11b40 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
11b50 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
11b60 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
11b70 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
11b80 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
11b90 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
11ba0 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
11bb0 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
11bc0 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
11bd0 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
11be0 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
11bf0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11c00 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
11c10 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
11c20 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11c30 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
11c40 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
11c50 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
11c60 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
11c70 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
11c80 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
11c90 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
11ca0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
11cb0 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
11cc0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
11cd0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
11ce0 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
11cf0 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
11d00 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
11d10 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
11d20 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
11d30 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11d40 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
11d50 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
11d60 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
11d70 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
11d80 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
11d90 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
11da0 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
11db0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
11dc0 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
11dd0 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
11de0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11df0 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
11e00 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
11e10 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
11e20 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
11e30 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
11e40 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
11e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11e60 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
11e70 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
11e80 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
11e90 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
11ea0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
11eb0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
11ec0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
11ed0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
11ee0 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
11ef0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
11f00 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
11f10 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
11f20 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
11f30 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
11f40 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
11f50 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
11f60 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
11f70 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
11f80 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
11f90 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
11fa0 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
11fb0 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
11fc0 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
11fd0 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
11fe0 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
11ff0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12000 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
12010 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
12020 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
12030 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
12040 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
12050 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
12060 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
12070 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
12080 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
12090 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
120a0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
120b0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
120c0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
120d0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
120e0 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
120f0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
12100 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12110 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
12120 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
12130 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
12140 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
12150 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
12160 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
12170 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
12180 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
12190 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
121a0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
121b0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
121c0 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
121d0 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
121e0 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
121f0 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
12200 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
12210 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
12220 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
12230 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
12240 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
12250 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
12260 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
12270 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12280 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
12290 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
122a0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
122b0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
122c0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
122d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
122e0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
122f0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
12300 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
12310 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
12320 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
12330 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
12340 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
12350 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
12360 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12370 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
12380 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
12390 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
123a0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
123b0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
123c0 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
123d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
123e0 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
123f0 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
12400 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
12410 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
12420 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
12430 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
12440 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
12450 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
12460 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
12470 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
12480 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
12490 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
124a0 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
124b0 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
124c0 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
124d0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
124e0 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
124f0 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
12500 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
12510 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
12520 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
12530 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
12540 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
12550 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73  ..**.** <b>The s
12560 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
12570 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
12580 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65   threadsafe. The
12590 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
125a0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
125b0 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
125c0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
125d0 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
125e0 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
125f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
12600 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f  () is running.</
12610 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  b>.**.** The sql
12620 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
12630 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f  terface.** may o
12640 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
12650 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
12660 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
12670 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
12680 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
12690 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
126a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
126b0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
126c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
126d0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
126e0 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
126f0 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
12700 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
12710 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
12720 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
12730 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
12740 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
12750 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
12760 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
12770 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
12780 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
12790 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
127a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
127b0 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
127c0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
127d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
127e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
127f0 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
12800 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
12810 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
12820 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
12830 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
12840 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
12850 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
12860 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
12870 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
12880 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
12890 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
128a0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
128b0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
128c0 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
128d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
128e0 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
128f0 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
12900 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
12910 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
12920 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
12930 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
12940 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
12950 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
12960 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
12970 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
12980 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
12990 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
129a0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
129b0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
129c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
129d0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
129e0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
129f0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
12a00 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
12a10 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
12a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
12a30 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
12a40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12a50 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
12a60 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
12a70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12a80 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
12a90 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
12aa0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
12ab0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
12ac0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
12ad0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
12ae0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
12af0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
12b00 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
12b10 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
12b20 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
12b30 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
12b40 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
12b50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
12b60 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
12b70 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
12b80 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
12b90 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
12ba0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12bb0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
12bc0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
12bd0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
12be0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
12bf0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12c00 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
12c10 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
12c20 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
12c30 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
12c40 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
12c50 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
12c60 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
12c70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12c80 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
12c90 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
12ca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12cb0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
12cc0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
12cd0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
12ce0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
12cf0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
12d00 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
12d10 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
12d20 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
12d30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12d40 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
12d50 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
12d60 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
12d70 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
12d80 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
12d90 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12da0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12db0 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
12dc0 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
12dd0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
12de0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
12df0 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
12e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12e10 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
12e20 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12e30 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
12e40 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
12e50 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
12e60 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
12e70 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
12e80 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
12e90 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
12ea0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
12eb0 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
12ec0 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
12ed0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
12ee0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12ef0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
12f00 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
12f10 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
12f20 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
12f30 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
12f40 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
12f50 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
12f60 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
12f70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
12f80 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
12f90 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
12fa0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
12fb0 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
12fc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
12fd0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
12fe0 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
12ff0 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
13000 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
13010 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
13020 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
13030 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
13040 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
13050 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
13060 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
13070 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
13080 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
13090 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
130a0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
130b0 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
130c0 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
130d0 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
130e0 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
130f0 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
13100 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
13110 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
13120 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
13130 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
13140 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
13150 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
13160 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
13170 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
13180 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
13190 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
131a0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
131b0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
131c0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
131d0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
131e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
131f0 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
13200 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
13210 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
13220 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
13230 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
13240 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
13250 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
13260 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
13270 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
13280 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
13290 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
132a0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
132b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
132c0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
132d0 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
132e0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
132f0 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
13300 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
13310 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
13320 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
13330 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
13340 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
13350 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
13360 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
13370 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
13380 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
13390 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
133a0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
133b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
133c0 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
133d0 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
133e0 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
133f0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
13400 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
13410 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
13420 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
13430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13440 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
13450 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
13460 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
13470 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
13480 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
13490 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
134a0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
134b0 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
134c0 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
134d0 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
134e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
134f0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
13500 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
13510 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
13520 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
13530 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
13540 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
13550 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
13560 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
13570 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
13580 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
13590 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
135a0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
135b0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
135c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
135d0 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
135e0 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
135f0 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
13600 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
13610 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
13620 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
13630 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
13640 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
13650 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
13660 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
13670 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
13680 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
13690 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
136a0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
136b0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
136c0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
136d0 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
136e0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
136f0 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
13700 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
13710 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
13720 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
13730 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
13740 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
13750 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
13760 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
13770 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
13780 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
13790 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
137a0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
137b0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
137c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
137d0 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
137e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
137f0 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
13800 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
13810 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
13820 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
13830 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
13840 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
13850 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
13860 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
13870 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
13880 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
13890 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
138a0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
138b0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
138c0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
138d0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
138e0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
138f0 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
13900 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
13910 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
13920 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
13930 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
13940 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
13950 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
13960 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
13970 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13980 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
13990 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
139a0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
139b0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
139c0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
139d0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
139e0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
139f0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
13a00 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
13a10 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
13a20 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
13a30 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
13a40 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
13a50 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
13a60 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
13a70 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
13a80 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
13a90 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
13aa0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
13ab0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
13ac0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
13ad0 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
13ae0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
13af0 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
13b00 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
13b10 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
13b20 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
13b30 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
13b40 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
13b50 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
13b60 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
13b70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13b80 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
13b90 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
13ba0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
13bb0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
13bc0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
13bd0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
13be0 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
13bf0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
13c00 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
13c10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
13c20 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
13c30 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
13c40 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
13c50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13c60 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
13c70 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
13c80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13c90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
13ca0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
13cb0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
13cc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13cd0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
13ce0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
13cf0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
13d00 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
13d10 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13d20 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
13d30 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
13d40 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
13d50 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
13d60 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
13d70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
13d80 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
13d90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
13da0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
13db0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
13dc0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
13dd0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
13de0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
13df0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
13e00 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
13e10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13e20 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
13e30 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
13e40 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13e50 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
13e60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13e70 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
13e80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
13e90 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
13ea0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
13eb0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
13ec0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
13ed0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
13ee0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
13ef0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
13f00 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
13f10 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
13f20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
13f30 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
13f40 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
13f50 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
13f60 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
13f70 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13f80 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13f90 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13fa0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13fb0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13fc0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13fd0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
13fe0 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
13ff0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
14000 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
14010 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
14020 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
14030 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
14040 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
14050 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
14060 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
14070 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
14080 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
14090 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
140a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
140b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
140c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
140d0 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
140e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
140f0 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
14100 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
14110 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
14120 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
14130 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14140 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14150 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
14160 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
14170 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
14180 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
14190 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
141a0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
141b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
141c0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
141d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
141e0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
141f0 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
14200 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
14210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
14220 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
14230 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
14240 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
14250 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
14260 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
14270 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
14280 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
14290 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
142a0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
142b0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
142c0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
142d0 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
142e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
142f0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
14300 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
14310 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
14320 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
14330 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
14340 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
14350 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14360 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
14370 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
14380 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
14390 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
143a0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
143b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
143c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
143d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
143e0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
143f0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
14400 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
14410 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14420 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
14440 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
14450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
14460 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
14470 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
14480 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
14490 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
144a0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
144b0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
144c0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
144d0 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
144e0 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
144f0 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
14500 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
14510 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
14520 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14540 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
14550 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
14560 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
14570 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
14580 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
14590 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
145a0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
145b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
145c0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
145d0 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
145e0 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
145f0 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
14600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
14610 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
14620 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
14630 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
14640 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
14650 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
14660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14670 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
14680 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14690 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
146a0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
146b0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
146c0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
146d0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
146e0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
146f0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14700 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14710 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14720 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
14730 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
14740 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
14750 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
14760 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
14770 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
14780 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
14790 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
147a0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
147b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
147c0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
147d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
147e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
147f0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
14800 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14810 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
14820 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14830 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14840 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
14850 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14860 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
14870 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
14880 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
14890 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
148a0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
148b0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
148c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
148d0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
148e0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
148f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
14900 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
14910 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
14920 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
14930 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
14940 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
14950 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
14960 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
14970 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
14980 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14990 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
149a0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
149b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
149c0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
149d0 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
149e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
149f0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
14a00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14a10 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
14a20 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14a30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
14a40 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
14a50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14a60 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
14a70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14a80 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14a90 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14aa0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
14ab0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
14ac0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
14ad0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
14ae0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
14af0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
14b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14b10 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
14b20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
14b30 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
14b40 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
14b50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14b60 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
14b70 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
14b80 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
14b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14ba0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
14bb0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
14bc0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
14bd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
14bf0 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  L_MALLOC]] <dt>S
14c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41  QLITE_CONFIG_SMA
14c10 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  LL_MALLOC</dt>.*
14c20 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
14c30 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f  TE_CONFIG_SMALL_
14c40 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
14c50 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
14c60 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20 69  ent of.** type i
14c70 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
14c80 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68  as a boolean, wh
14c90 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f 76  ich if true prov
14ca0 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a 2a  ides a hint to.*
14cb0 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74  * SQLite that it
14cc0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c 61   should avoid la
14cd0 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  rge memory alloc
14ce0 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69 62  ations if possib
14cf0 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  le..** SQLite wi
14d00 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69 66  ll run faster if
14d10 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20 6d   it is free to m
14d20 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79  ake large memory
14d30 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a   allocations,.**
14d40 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69 63   but some applic
14d50 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65 66  ation might pref
14d60 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65 72  er to run slower
14d70 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f 72   in exchange for
14d80 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 61  .** guarantees a
14d90 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61 67  bout memory frag
14da0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 61  mentation that a
14db0 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20 6c  re possible if l
14dc0 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  arge.** allocati
14dd0 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64 2e  ons are avoided.
14de0 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
14df0 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20  ormally off..** 
14e00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14e20 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
14e30 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
14e40 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
14e50 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
14e60 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
14e70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
14e80 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
14e90 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
14ea0 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
14eb0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
14ec0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
14ed0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
14ee0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
14ef0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
14f00 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
14f10 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14f20 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
14f30 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
14f40 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
14f50 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
14f60 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
14f70 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
14f80 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
14f90 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
14fa0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
14fb0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
14fc0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
14fd0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
14fe0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
14ff0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
15000 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tus64()].**   </
15010 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
15020 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
15030 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
15040 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
15050 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
15060 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
15070 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
15080 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
15090 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
150a0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
150b0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
150c0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
150d0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
150e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
150f0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
15100 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
15110 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
15120 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
15130 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70  ONFIG_SCRATCH op
15140 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  tion is no longe
15150 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e  r used..** </dd>
15160 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15170 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15180 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15190 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
151a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
151b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
151c0 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
151d0 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f  specifies a memo
151e0 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20  ry pool.** that 
151f0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
15200 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
15210 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
15220 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
15230 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
15240 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
15250 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
15260 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f  n option is a no
15270 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63  -op if an applic
15280 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
15290 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
152a0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
152b0 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ded using the [S
152c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
152d0 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65  CHE2]..** ^There
152e0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
152f0 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
15300 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a  ONFIG_PAGECACHE:
15310 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   A pointer to.**
15320 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
15330 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74  memory (pMem), t
15340 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
15350 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
15360 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
15370 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65   number of cache
15380 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   lines (N)..** T
15390 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
153a0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
153b0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
153c0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
153d0 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
153e0 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
153f0 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f  d 65536) plus so
15400 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66  me extra bytes f
15410 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
15420 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75  header.  ^The nu
15430 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79  mber of extra by
15440 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68  tes needed by th
15450 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a  e page header.**
15460 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
15470 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45  ed using [SQLITE
15480 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15490 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73  DRSZ]..** ^It is
154a0 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
154b0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
154c0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20   memory,.** for 
154d0 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  the sz parameter
154e0 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68   to be larger th
154f0 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54  an necessary.  T
15500 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d  he pMem.** argum
15510 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68  ent must be eith
15520 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
15530 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  r or a pointer t
15540 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  o an 8-byte.** a
15550 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20  ligned block of 
15560 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61  memory of at lea
15570 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f  st sz*N bytes, o
15580 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73  therwise.** subs
15590 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
155a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
155b0 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e   ^When pMem is n
155c0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
155d0 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75  will strive to u
155e0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
155f0 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74  ovided.** to sat
15600 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20  isfy page cache 
15610 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62  needs, falling b
15620 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ack to [sqlite3_
15630 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20  malloc()] if.** 
15640 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  a page cache lin
15650 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e  e is larger than
15660 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20   sz bytes or if 
15670 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20  all of the pMem 
15680 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68  buffer.** is exh
15690 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70  austed..** ^If p
156a0 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20  Mem is NULL and 
156b0 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  N is non-zero, t
156c0 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73  hen each databas
156d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
156e0 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20  does an initial 
156f0 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  bulk allocation 
15700 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
15710 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73  emory.** from [s
15720 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15730 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20   sufficient for 
15740 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66  N cache lines if
15750 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f   N is positive o
15760 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20  r.** of -1024*N 
15770 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65  bytes if N is ne
15780 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64  gative, . ^If ad
15790 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
157a0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
157b0 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
157c0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
157d0 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a  by the initial.*
157e0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  * allocation, th
157f0 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  en SQLite goes t
15800 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
15810 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20  c()] separately 
15820 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69  for each.** addi
15830 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e  tional cache lin
15840 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
15850 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
15860 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
15870 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
15880 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
15890 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
158a0 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  P option specifi
158b0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
158c0 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68  ry buffer .** th
158d0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
158e0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
158f0 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
15900 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
15910 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73  s.** beyond thos
15920 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62  e provided for b
15930 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
15940 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
15950 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15960 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
15970 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
15980 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
15990 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
159a0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
159b0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
159c0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
159d0 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
159e0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
159f0 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
15a00 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
15a10 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
15a20 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
15a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15a40 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
15a50 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
15a60 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
15a70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
15a80 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
15a90 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
15aa0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
15ab0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
15ac0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
15ad0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
15ae0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
15af0 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
15b00 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
15b10 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
15b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
15b30 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
15b40 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
15b50 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
15b60 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
15b70 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
15b80 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
15b90 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
15ba0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
15bb0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
15bc0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
15bd0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
15be0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
15bf0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
15c00 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
15c10 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
15c20 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
15c30 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
15c40 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
15c50 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
15c60 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
15c70 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
15c80 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
15c90 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
15ca0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
15cb0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
15cc0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
15cd0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
15ce0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
15cf0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
15d00 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
15d10 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
15d20 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
15d30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
15d40 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
15d50 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
15d60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
15d70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15d80 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
15d90 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15da0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
15db0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
15dc0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
15dd0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
15de0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
15df0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
15e00 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
15e10 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
15e20 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
15e30 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
15e40 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
15e50 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
15e60 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
15e70 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
15e80 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
15e90 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
15ea0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
15eb0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
15ec0 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
15ed0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
15ee0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
15ef0 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
15f00 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15f10 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
15f20 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
15f30 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
15f40 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
15f50 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
15f60 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
15f70 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
15f80 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
15f90 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
15fa0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
15fb0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
15fc0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
15fd0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
15fe0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15ff0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
16000 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
16010 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16020 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
16030 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
16040 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
16050 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
16060 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16070 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
16080 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16090 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
160a0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
160b0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
160c0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
160d0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
160e0 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
160f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
16100 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
16110 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
16120 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
16130 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
16140 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
16150 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
16160 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
16170 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
16180 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
16190 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
161a0 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
161b0 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
161c0 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
161d0 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
161e0 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
161f0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
16200 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
16210 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
16220 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
16230 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
16240 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
16250 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
16260 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
16270 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
16280 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
16290 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
162a0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
162b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
162c0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
162d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
162e0 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
162f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
16300 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
16310 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
16320 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16330 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16340 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16350 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
16360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
16370 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16380 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
16390 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
163a0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
163b0 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
163c0 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
163d0 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
163e0 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
163f0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
16400 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16410 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
16420 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
16430 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
16440 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
16450 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
16460 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
16470 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
16480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
16490 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
164a0 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
164b0 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
164c0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
164d0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
164e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
164f0 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
16500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
16510 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
16520 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
16530 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
16540 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
16550 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
16560 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
16570 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16580 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
16590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
165a0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
165b0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
165c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
165d0 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
165e0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
165f0 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
16600 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
16610 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
16620 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
16630 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
16640 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
16650 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
16660 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
16670 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
16680 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
16690 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
166a0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
166b0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
166c0 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
166d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
166e0 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
166f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16700 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
16710 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
16720 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
16730 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
16740 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16750 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
16760 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
16770 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
16780 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
16790 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
167a0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
167b0 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
167c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
167d0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
167e0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
167f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16800 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16810 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
16820 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
16830 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
16840 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
16850 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
16860 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
16870 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
16880 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16890 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
168a0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
168b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
168c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
168d0 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
168e0 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
168f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
16900 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
16910 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
16920 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
16930 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
16940 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
16950 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
16960 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
16970 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
16980 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
16990 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
169a0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
169b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
169c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
169d0 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
169e0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
169f0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
16a00 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16a10 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
16a20 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
16a30 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
16a40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
16a50 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
16a60 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
16a70 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
16a80 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
16a90 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
16aa0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
16ab0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
16ac0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
16ad0 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
16ae0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
16af0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
16b00 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
16b10 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
16b20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
16b30 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
16b40 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
16b50 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
16b60 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
16b70 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
16b80 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
16b90 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
16ba0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
16bb0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
16bc0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
16bd0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
16be0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
16bf0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
16c00 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
16c10 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
16c20 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
16c30 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
16c40 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
16c50 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
16c60 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
16c70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
16c80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
16c90 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
16ca0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
16cb0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
16cc0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16cd0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
16ce0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16cf0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
16d00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16d10 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
16d20 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
16d30 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
16d40 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
16d50 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
16d60 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
16d70 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
16d80 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
16d90 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
16da0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
16db0 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
16dc0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
16dd0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
16de0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
16df0 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
16e00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
16e10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
16e20 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
16e30 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
16e40 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
16e50 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
16e60 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
16e70 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
16e80 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
16e90 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
16ea0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
16eb0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
16ec0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
16ed0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
16ee0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
16ef0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
16f00 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
16f10 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
16f20 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
16f30 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
16f40 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
16f50 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
16f60 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
16f70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
16f80 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
16f90 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
16fa0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
16fb0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
16fc0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
16fd0 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
16fe0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
16ff0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
17000 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
17010 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
17020 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
17030 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
17040 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17050 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
17060 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
17070 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17080 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
17090 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
170a0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
170b0 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
170c0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
170d0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
170e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
170f0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
17100 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
17110 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
17120 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
17130 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
17140 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
17150 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
17160 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
17170 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
17180 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
17190 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
171a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
171b0 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
171c0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
171d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
171e0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
171f0 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
17200 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
17210 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
17220 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
17230 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
17240 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
17250 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
17260 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
17270 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
17280 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
17290 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
172a0 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
172b0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
172c0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
172d0 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
172e0 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
172f0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
17300 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
17310 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
17320 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
17330 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
17340 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17350 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
17360 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17370 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
17380 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17390 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
173a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
173b0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
173c0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
173d0 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
173e0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
173f0 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
17400 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
17410 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
17420 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
17430 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
17440 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
17450 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17460 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
17470 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
17480 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
17490 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
174a0 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
174b0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
174c0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
174d0 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
174e0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
174f0 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
17500 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17510 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
17520 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
17530 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
17540 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
17550 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
17560 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
17570 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
17580 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
17590 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
175a0 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
175b0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
175c0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
175d0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
175e0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
175f0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
17600 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
17610 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
17620 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
17630 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
17640 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17650 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
17660 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
17670 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
17680 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
17690 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
176a0 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
176b0 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
176c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
176d0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
176e0 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
176f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
17700 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
17710 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
17720 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
17730 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
17740 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
17750 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
17760 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
17770 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
17780 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
17790 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
177a0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
177b0 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
177c0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
177d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
177e0 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
177f0 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
17800 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
17810 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
17820 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
17830 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
17840 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
17850 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
17860 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
17870 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
17880 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
17890 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
178a0 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
178b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
178c0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
178d0 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
178e0 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
178f0 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
17900 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
17910 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
17920 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
17930 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
17940 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
17950 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
17960 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
17970 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
17980 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
17990 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
179a0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
179b0 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
179c0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
179d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
179e0 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
179f0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
17a00 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
17a10 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
17a20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
17a30 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
17a40 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
17a50 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
17a60 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
17a70 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
17a80 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
17a90 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
17aa0 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
17ab0 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
17ac0 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
17ad0 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
17ae0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
17af0 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
17b00 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
17b10 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
17b20 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
17b30 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
17b40 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
17b50 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
17b60 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
17b70 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
17b80 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
17b90 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
17ba0 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
17bb0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17bc0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
17bd0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
17be0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17bf0 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
17c00 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
17c10 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
17c20 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
17c30 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
17c40 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
17c50 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
17c60 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
17c70 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
17c80 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17c90 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
17ca0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
17cb0 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
17cc0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
17cd0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
17ce0 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
17cf0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
17d00 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17d10 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  DRSZ]].** <dt>SQ
17d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17d30 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e  HE_HDRSZ.** <dd>
17d40 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
17d50 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
17d60 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
17d70 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
17d80 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
17d90 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
17da0 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69  ger and writes i
17db0 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
17dc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
17dd0 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65  xtra.** bytes pe
17de0 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20  r page required 
17df0 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e  for each page in
17e00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
17e10 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
17e20 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74  he amount of ext
17e30 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ra space require
17e40 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70  d can change dep
17e50 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
17e60 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65  mpiler,.** targe
17e70 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20  t platform, and 
17e80 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a  SQLite version..
17e90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17ea0 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a  ONFIG_PMASZ]].**
17eb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17ec0 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e  IG_PMASZ.** <dd>
17ed0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
17ee0 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20  IG_PMASZ option 
17ef0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
17f00 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
17f10 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  * is an unsigned
17f20 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74   integer and set
17f30 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50  s the "Minimum P
17f40 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65  MA Size" for the
17f50 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a   multithreaded.*
17f60 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74  * sorter to that
17f70 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64   integer.  The d
17f80 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50  efault minimum P
17f90 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62  MA Size is set b
17fa0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
17fb0 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63  _SORTER_PMASZ] c
17fc0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17fd0 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73  on.  New threads
17fe0 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a   are launched.**
17ff0 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f   to help with so
18000 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68  rt operations wh
18010 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  en multithreaded
18020 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65   sorting.** is e
18030 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68  nabled (using th
18040 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64  e [PRAGMA thread
18050 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20  s] command) and 
18060 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  the amount of co
18070 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73  ntent.** to be s
18080 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68  orted exceeds th
18090 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65  e page size time
180a0 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66  s the minimum of
180b0 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   the.** [PRAGMA 
180c0 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74  cache_size] sett
180d0 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c  ing and this val
180e0 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ue..**.** [[SQLI
180f0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
18100 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64  NL_SPILL]].** <d
18110 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
18120 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a  STMTJRNL_SPILL.*
18130 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
18140 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
18150 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74  L_SPILL option t
18160 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
18170 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
18180 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74   becomes the [st
18190 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d  atement journal]
181a0 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74   spill-to-disk t
181b0 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b  hreshold.  .** [
181c0 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  Statement journa
181d0 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20  ls] are held in 
181e0 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65  memory until the
181f0 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65  ir size (in byte
18200 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68  s).** exceeds th
18210 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74  is threshold, at
18220 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65   which point the
18230 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f  y are written to
18240 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20   disk..** Or if 
18250 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73  the threshold is
18260 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a   -1, statement j
18270 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61  ournals are alwa
18280 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75  ys held.** exclu
18290 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79  sively in memory
182a0 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20  ..** Since many 
182b0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
182c0 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20  ls never become 
182d0 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74  large, setting t
182e0 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65  he spill.** thre
182f0 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65  shold to a value
18300 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 63   such as 64KiB c
18310 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 63  an greatly reduc
18320 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a  e the amount of.
18330 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20  ** I/O required 
18340 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 65  to support state
18350 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ment rollback..*
18360 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  * The default va
18370 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 74  lue for this set
18380 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c  ting is controll
18390 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  ed by the.** [SQ
183a0 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  LITE_STMTJRNL_SP
183b0 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ILL] compile-tim
183c0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  e option..**.** 
183d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
183e0 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 5d 5d  SORTERREF_SIZE]]
183f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
18400 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f  ONFIG_SORTERREF_
18410 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  SIZE.** <dd>The 
18420 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4f  SQLITE_CONFIG_SO
18430 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f 70 74  RTERREF_SIZE opt
18440 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73 69  ion accepts a si
18450 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ngle parameter.*
18460 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74 29 20  * of type (int) 
18470 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75 65 20  - the new value 
18480 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d 72 65  of the sorter-re
18490 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68 72  ference size thr
184a0 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75 61 6c  eshold..** Usual
184b0 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ly, when SQLite 
184c0 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e 61 6c  uses an external
184d0 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72 20 72   sort to order r
184e0 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69 6e 67  ecords according
184f0 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45 52 20  .** to an ORDER 
18500 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c 20 66  BY clause, all f
18510 69 65 6c 64 73 20 72 65 71 75 69 72 65 64 20 62  ields required b
18520 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61 72 65  y the caller are
18530 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 0a   present in the.
18540 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f 72 64  ** sorted record
18550 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  s. However, if S
18560 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
18570 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 64 65   based on the de
18580 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a 20 6f  clared type.** o
18590 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  f a table column
185a0 20 74 68 61 74 20 69 74 73 20 76 61 6c 75 65 73   that its values
185b0 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
185c0 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d 20 6c  e very large - l
185d0 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20 74 68  arger.** than th
185e0 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73 6f 72  e configured sor
185f0 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73 69  ter-reference si
18600 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d 20 74  ze threshold - t
18610 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63 65 0a  hen a reference.
18620 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  ** is stored in 
18630 65 61 63 68 20 73 6f 72 74 65 64 20 72 65 63 6f  each sorted reco
18640 72 64 20 61 6e 64 20 74 68 65 20 72 65 71 75 69  rd and the requi
18650 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  red column value
18660 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72 6f 6d  s loaded.** from
18670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 73   the database as
18680 20 72 65 63 6f 72 64 73 20 61 72 65 20 72 65 74   records are ret
18690 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65 64 20  urned in sorted 
186a0 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66 61 75  order. The defau
186b0 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20  lt.** value for 
186c0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 74  this option is t
186d0 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68 69 73  o never use this
186e0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 53   optimization. S
186f0 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a 2a 20  pecifying a .** 
18700 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
18710 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 72  or this option r
18720 65 73 74 6f 72 65 73 20 74 68 65 20 64 65 66 61  estores the defa
18730 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e 0a 2a  ult behaviour..*
18740 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  * This option is
18750 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
18760 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
18770 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
18780 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
18790 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45 4e 43  _SORTER_REFERENC
187a0 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ES] compile-time
187b0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b   option..**.** [
187c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
187d0 45 4d 44 42 5f 4d 41 58 53 49 5a 45 5d 5d 0a 2a  EMDB_MAXSIZE]].*
187e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
187f0 46 49 47 5f 4d 45 4d 44 42 5f 4d 41 58 53 49 5a  FIG_MEMDB_MAXSIZ
18800 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c  E.** <dd>The SQL
18810 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 44 42  ITE_CONFIG_MEMDB
18820 5f 4d 41 58 53 49 5a 45 20 6f 70 74 69 6f 6e 20  _MAXSIZE option 
18830 61 63 63 65 70 74 73 20 61 20 73 69 6e 67 6c 65  accepts a single
18840 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 5b 73   parameter.** [s
18850 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 70 61  qlite3_int64] pa
18860 72 61 6d 65 74 65 72 20 77 68 69 63 68 20 69 73  rameter which is
18870 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61 78   the default max
18880 69 6d 75 6d 20 73 69 7a 65 20 66 6f 72 20 61 6e  imum size for an
18890 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61   in-memory.** da
188a0 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
188b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 64 65  sing [sqlite3_de
188c0 73 65 72 69 61 6c 69 7a 65 28 29 5d 2e 20 20 54  serialize()].  T
188d0 68 69 73 20 64 65 66 61 75 6c 74 20 6d 61 78 69  his default maxi
188e0 6d 75 6d 0a 2a 2a 20 73 69 7a 65 20 63 61 6e 20  mum.** size can 
188f0 62 65 20 61 64 6a 75 73 74 65 64 20 75 70 20 6f  be adjusted up o
18900 72 20 64 6f 77 6e 20 66 6f 72 20 69 6e 64 69 76  r down for indiv
18910 69 64 75 61 6c 20 64 61 74 61 62 61 73 65 73 20  idual databases 
18920 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
18930 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
18940 4c 49 4d 49 54 5d 20 5b 73 71 6c 69 74 65 33 5f  LIMIT] [sqlite3_
18950 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 7c 66 69 6c  file_control|fil
18960 65 2d 63 6f 6e 74 72 6f 6c 5d 2e 20 20 49 66 20  e-control].  If 
18970 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
18980 61 74 69 6f 6e 20 73 65 74 74 69 6e 67 20 69 73  ation setting is
18990 20 6e 65 76 65 72 20 75 73 65 64 2c 20 74 68 65   never used, the
189a0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61  n the default ma
189b0 78 69 6d 75 6d 20 69 73 20 64 65 74 65 72 6d 69  ximum is determi
189c0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
189d0 51 4c 49 54 45 5f 4d 45 4d 44 42 5f 44 45 46 41  QLITE_MEMDB_DEFA
189e0 55 4c 54 5f 4d 41 58 53 49 5a 45 5d 20 63 6f 6d  ULT_MAXSIZE] com
189f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
18a00 2e 20 20 49 66 20 74 68 61 74 0a 2a 2a 20 63 6f  .  If that.** co
18a10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
18a20 6e 20 69 73 20 6e 6f 74 20 73 65 74 2c 20 74 68  n is not set, th
18a30 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  en the default m
18a40 61 78 69 6d 75 6d 20 69 73 20 31 30 37 33 37 34  aximum is 107374
18a50 31 38 32 34 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  1824..** </dl>.*
18a60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a70 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
18a80 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
18a90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18aa0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
18ab0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
18ac0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ad0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
18ae0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
18af0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
18b00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
18b10 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
18b20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
18b30 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
18b40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18b50 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
18b60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
18b70 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
18b80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18b90 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
18ba0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
18bb0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
18bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
18bd0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
18be0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
18bf0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
18c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
18c10 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
18c20 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
18c30 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
18c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18c50 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
18c60 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
18c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18c80 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
18c90 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
18ca0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
18cb0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
18cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18cd0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
18ce0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
18cf0 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
18d00 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
18d10 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
18d20 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
18d30 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
18d40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18d50 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
18d60 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
18d70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18d80 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
18d90 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
18da0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
18db0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
18dc0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
18dd0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
18de0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
18df0 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
18e00 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
18e10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18e20 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
18e30 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
18e40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e50 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
18e60 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
18e70 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
18e80 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
18e90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18ea0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
18eb0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
18ec0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
18ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18ee0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
18ef0 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
18f00 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
18f20 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
18f30 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
18f40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18f50 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
18f60 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
18f70 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
18f80 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
18f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18fa0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
18fb0 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
18fc0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
18fd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18fe0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20  G_PCACHE_HDRSZ  
18ff0 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74        24  /* int
19000 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65   *psz */.#define
19010 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
19020 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20  MASZ            
19030 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e     25  /* unsign
19040 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a  ed int szPma */.
19050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19060 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
19070 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a  PILL      26  /*
19080 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64   int nByte */.#d
19090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
190a0 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43  FIG_SMALL_MALLOC
190b0 20 20 20 20 20 20 20 20 32 37 20 20 2f 2a 20 62          27  /* b
190c0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
190d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
190e0 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 20  SORTERREF_SIZE  
190f0 20 20 20 20 32 38 20 20 2f 2a 20 69 6e 74 20 6e      28  /* int n
19100 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
19110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
19120 4d 44 42 5f 4d 41 58 53 49 5a 45 20 20 20 20 20  MDB_MAXSIZE     
19130 20 20 32 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    29  /* sqlite3
19140 5f 69 6e 74 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  _int64 */../*.**
19150 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
19160 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
19170 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
19180 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
19190 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
191a0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
191b0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
191c0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
191d0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
191e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
191f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
19200 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
19210 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
19220 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
19230 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
19240 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
19250 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
19260 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
19270 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
19280 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
19290 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
192a0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
192b0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
192c0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
192d0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
192e0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
192f0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
19300 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
19310 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
19320 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
19330 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
19340 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
19350 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
19360 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
19370 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
19380 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
19390 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
193a0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
193b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ** [[SQLITE_DBCO
193c0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
193d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
193e0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
193f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
19400 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
19410 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
19420 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
19430 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
19440 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
19450 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
19460 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
19470 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
19480 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
19490 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
194a0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
194b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
194c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
194d0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
194e0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
194f0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
19500 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
19510 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
19520 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
19530 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
19540 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
19550 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
19560 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
19570 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
19580 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
19590 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
195a0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
195b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
195c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
195d0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
195e0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
195f0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
19600 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
19610 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
19620 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
19630 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
19640 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
19650 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
19660 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
19670 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
19680 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
19690 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
196a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
196b0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
196c0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
196d0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
196e0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
196f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
19700 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
19710 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
19720 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
19730 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
19740 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
19750 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
19760 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
19770 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
19780 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
19790 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
197a0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
197b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
197c0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
197d0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
197e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
197f0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
19800 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
19810 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
19820 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
19830 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
19840 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
19850 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
19860 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
19870 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
19880 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
19890 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
198a0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
198b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
198c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
198d0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
198e0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
198f0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
19900 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
19910 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
19920 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
19930 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
19940 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19950 45 4e 41 42 4c 45 5f 46 4b 45 59 5d 5d 0a 2a 2a  ENABLE_FKEY]].**
19960 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19970 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
19980 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19990 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
199a0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
199b0 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
199c0 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
199d0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
199e0 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
199f0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
19a00 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
19a10 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
19a20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
19a30 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
19a40 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
19a50 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
19a60 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19a70 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
19a80 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
19a90 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
19aa0 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
19ab0 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
19ac0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19ad0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19ae0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19af0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19b00 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19b10 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
19b20 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
19b30 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
19b40 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
19b50 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19b60 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
19b70 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
19b80 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
19b90 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
19ba0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
19bb0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
19bc0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
19bd0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19be0 45 5f 54 52 49 47 47 45 52 5d 5d 0a 2a 2a 20 3c  E_TRIGGER]].** <
19bf0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19c00 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
19c10 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
19c20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
19c30 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
19c40 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
19c50 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
19c60 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
19c70 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
19c80 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
19c90 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
19ca0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
19cb0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
19cc0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
19cd0 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
19ce0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
19cf0 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
19d00 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
19d10 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
19d20 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
19d30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
19d40 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
19d50 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
19d60 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
19d70 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
19d80 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
19d90 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
19da0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
19db0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
19dc0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
19dd0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
19de0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
19df0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
19e00 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
19e10 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
19e20 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
19e30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  **.** [[SQLITE_D
19e40 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
19e50 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 5d 5d 0a  TS3_TOKENIZER]].
19e60 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
19e70 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
19e80 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74  S3_TOKENIZER</dt
19e90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
19ea0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
19eb0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
19ec0 62 6c 65 20 74 68 65 0a 2a 2a 20 5b 66 74 73 33  ble the.** [fts3
19ed0 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75  _tokenizer()] fu
19ee0 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20  nction which is 
19ef0 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  part of the.** [
19f00 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20  FTS3] full-text 
19f10 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78  search engine ex
19f20 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72  tension..** Ther
19f30 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
19f40 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
19f50 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
19f60 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
19f70 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
19f80 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
19f90 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
19fa0 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20   or.** positive 
19fb0 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74  to enable fts3_t
19fc0 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65  okenizer() or ne
19fd0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
19fe0 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  the setting.** u
19ff0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
1a000 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a010 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1a020 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1a030 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
1a040 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1a050 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1a060 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20   fts3_tokenizer 
1a070 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
1a080 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
1a090 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
1a0a0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1a0b0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
1a0c0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
1a0d0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
1a0e0 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
1a0f0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
1a100 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  k. </dd>.**.** [
1a110 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
1a120 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
1a130 45 4e 53 49 4f 4e 5d 5d 0a 2a 2a 20 3c 64 74 3e  ENSION]].** <dt>
1a140 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a150 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
1a160 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  NSION</dt>.** <d
1a170 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
1a180 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
1a190 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
1a1a0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
1a1b0 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69  xtension()].** i
1a1c0 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e  nterface indepen
1a1d0 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c  dently of the [l
1a1e0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
1a1f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
1a200 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  * The [sqlite3_e
1a210 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
1a220 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62  sion()] API enab
1a230 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
1a240 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50  both the.** C-AP
1a250 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  I [sqlite3_load_
1a260 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64  extension()] and
1a270 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
1a280 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  n [load_extensio
1a290 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  n()]..** There s
1a2a0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
1a2b0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
1a2c0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66  s..** When the f
1a2d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1a2e0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1a2f0 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20  is 1, then only 
1a300 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20  the C-API is.** 
1a310 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20  enabled and the 
1a320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d  SQL function rem
1a330 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20  ains disabled.  
1a340 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
1a350 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73  ument to.** this
1a360 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c   interface is 0,
1a370 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43   then both the C
1a380 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c  -API and the SQL
1a390 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69   function are di
1a3a0 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68  sabled..** If th
1a3b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a3c0 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20   is -1, then no 
1a3d0 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65  changes are made
1a3e0 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74   to state of eit
1a3f0 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49  her the.** C-API
1a400 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63   or the SQL func
1a410 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63  tion..** The sec
1a420 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1a430 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
1a440 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
1a450 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
1a460 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
1a470 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73 71  cate whether [sq
1a480 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
1a490 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63  sion()] interfac
1a4a0 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64  e.** is disabled
1a4b0 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c   or enabled foll
1a4c0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
1a4d0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
1a4e0 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65  ameter may.** be
1a4f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1a500 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
1a510 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69  he new setting i
1a520 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
1a530 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ack..** </dd>.**
1a540 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43  .** [[SQLITE_DBC
1a550 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45  ONFIG_MAINDBNAME
1a560 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ]] <dt>SQLITE_DB
1a570 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d  CONFIG_MAINDBNAM
1a580 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
1a590 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
1a5a0 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
1a5b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d  e name of the "m
1a5c0 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a  ain" database.**
1a5d0 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73   schema.  ^The s
1a5e0 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ole argument is 
1a5f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63  a pointer to a c
1a600 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74 72  onstant UTF8 str
1a610 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c  ing.** which wil
1a620 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77  l become the new
1a630 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20   schema name in 
1a640 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e  place of "main".
1a650 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65    ^SQLite.** doe
1a660 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70  s not make a cop
1a670 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69  y of the new mai
1a680 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74  n schema name st
1a690 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70  ring, so the app
1a6a0 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
1a6b0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1a6c0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
1a6d0 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e   into this DBCON
1a6e0 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  FIG option is un
1a6f0 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c  changed.** until
1a700 20 61 66 74 65 72 20 74 68 65 20 64 61 74 61 62   after the datab
1a710 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
1a720 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  loses..** </dd>.
1a730 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 44  **.** [[SQLITE_D
1a740 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
1a750 4f 4e 5f 43 4c 4f 53 45 5d 5d 20 0a 2a 2a 20 3c  ON_CLOSE]] .** <
1a760 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1a770 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c  IG_NO_CKPT_ON_CL
1a780 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  OSE</dt>.** <dd>
1a790 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61   Usually, when a
1a7a0 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61 6c   database in wal
1a7b0 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64 20   mode is closed 
1a7c0 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f 6d  or detached from
1a7d0 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   a .** database 
1a7e0 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20 63  handle, SQLite c
1a7f0 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77 69  hecks if this wi
1a800 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ll mean that the
1a810 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a  re are now no .*
1a820 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74  * connections at
1a830 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74 61   all to the data
1a840 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74 20  base. If so, it 
1a850 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63 6b  performs a check
1a860 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74  point .** operat
1a870 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73 69  ion before closi
1a880 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ng the connectio
1a890 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d  n. This option m
1a8a0 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a  ay be used to.**
1a8b0 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20 62   override this b
1a8c0 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66 69  ehaviour. The fi
1a8d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61  rst parameter pa
1a8e0 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65  ssed to this ope
1a8f0 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20  ration.** is an 
1a900 69 6e 74 65 67 65 72 20 2d 20 70 6f 73 69 74 69  integer - positi
1a910 76 65 20 74 6f 20 64 69 73 61 62 6c 65 20 63 68  ve to disable ch
1a920 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f  eckpoints-on-clo
1a930 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68 65  se, or zero (the
1a940 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f 20  .** default) to 
1a950 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20 61 6e 64  enable them, and
1a960 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
1a970 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
1a980 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
1a990 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a9a0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1a9b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  o an integer.** 
1a9c0 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72  into which is wr
1a9d0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1a9e0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1a9f0 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
1aa00 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62 65  close.** have be
1aa10 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30 20  en disabled - 0 
1aa20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  if they are not 
1aa30 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20 74  disabled, 1 if t
1aa40 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64  hey are..** </dd
1aa50 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
1aa60 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1aa70 5f 51 50 53 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  _QPSG]] <dt>SQLI
1aa80 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1aa90 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20  LE_QPSG</dt>.** 
1aaa0 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45  <dd>^(The SQLITE
1aab0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1aac0 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61 63 74  _QPSG option act
1aad0 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69  ivates or deacti
1aae0 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b 71 75  vates.** the [qu
1aaf0 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74 61 62  ery planner stab
1ab00 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65 65 5d  ility guarantee]
1ab10 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e 20 74   (QPSG).  When t
1ab20 68 65 20 51 50 53 47 20 69 73 20 61 63 74 69 76  he QPSG is activ
1ab30 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 53  e,.** a single S
1ab40 51 4c 20 71 75 65 72 79 20 73 74 61 74 65 6d 65  QL query stateme
1ab50 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75  nt will always u
1ab60 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  se the same algo
1ab70 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65 73 73  rithm regardless
1ab80 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20 6f 66  .** of values of
1ab90 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
1aba0 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53 47 20  rs].)^ The QPSG 
1abb0 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20 71 75  disables some qu
1abc0 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ery optimization
1abd0 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b 20 61  s.** that look a
1abe0 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20  t the values of 
1abf0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
1ac00 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61 6b 65  , which can make
1ac10 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a 2a 2a   some queries.**
1ac20 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20 74 68   slower.  But th
1ac30 65 20 51 50 53 47 20 68 61 73 20 74 68 65 20 61  e QPSG has the a
1ac40 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f 72 65  dvantage of more
1ac50 20 70 72 65 64 69 63 74 61 62 6c 65 20 62 65 68   predictable beh
1ac60 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a 2a 20  avior.  With.** 
1ac70 74 68 65 20 51 50 53 47 20 61 63 74 69 76 65 2c  the QPSG active,
1ac80 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
1ac90 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
1aca0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e 20 74   query plan in t
1acb0 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a 20 77  he field as.** w
1acc0 61 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  as used during t
1acd0 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20 6c 61  esting in the la
1ace0 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  b..** The first 
1acf0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
1ad00 20 73 65 74 74 69 6e 67 20 69 73 20 61 6e 20 69   setting is an i
1ad10 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
1ad20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 0a 2a 2a  0 to disable .**
1ad30 20 74 68 65 20 51 50 53 47 2c 20 70 6f 73 69 74   the QPSG, posit
1ad40 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 51 50  ive to enable QP
1ad50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20  SG, or negative 
1ad60 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
1ad70 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ting.** unchange
1ad80 64 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  d. The second pa
1ad90 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1ada0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
1adb0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
1adc0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
1add0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
1ade0 68 65 74 68 65 72 20 74 68 65 20 51 50 53 47 20  hether the QPSG 
1adf0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
1ae00 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
1ae10 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 0a 2a  ing this call..*
1ae20 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
1ae30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1ae40 54 52 49 47 47 45 52 5f 45 51 50 5d 5d 20 3c 64  TRIGGER_EQP]] <d
1ae50 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1ae60 47 5f 54 52 49 47 47 45 52 5f 45 51 50 3c 2f 64  G_TRIGGER_EQP</d
1ae70 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 20 64 65  t>.** <dd> By de
1ae80 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 74 70 75  fault, the outpu
1ae90 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 51 55 45  t of EXPLAIN QUE
1aea0 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e 64 73  RY PLAN commands
1aeb0 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20 69 6e   does not .** in
1aec0 63 6c 75 64 65 20 6f 75 74 70 75 74 20 66 6f 72  clude output for
1aed0 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e 73 20   any operations 
1aee0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 72 69  performed by tri
1aef0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 54  gger programs. T
1af00 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  his.** option is
1af10 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
1af20 63 6c 65 61 72 20 28 74 68 65 20 64 65 66 61 75  clear (the defau
1af30 6c 74 29 20 61 20 66 6c 61 67 20 74 68 61 74 20  lt) a flag that 
1af40 67 6f 76 65 72 6e 73 20 74 68 69 73 0a 2a 2a 20  governs this.** 
1af50 62 65 68 61 76 69 6f 72 2e 20 54 68 65 20 66 69  behavior. The fi
1af60 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 61  rst parameter pa
1af70 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 65  ssed to this ope
1af80 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e 74  ration is an int
1af90 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73 69 74 69  eger -.** positi
1afa0 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 6f 75 74  ve to enable out
1afb0 70 75 74 20 66 6f 72 20 74 72 69 67 67 65 72 20  put for trigger 
1afc0 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 7a 65 72  programs, or zer
1afd0 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 69 74 2c  o to disable it,
1afe0 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69 76 65 20  .** or negative 
1aff0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
1b000 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
1b010 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
1b020 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1b030 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
1b040 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  er into which is
1b050 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 30 20 6f   written .** 0 o
1b060 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
1b070 77 68 65 74 68 65 72 20 6f 75 74 70 75 74 2d 66  whether output-f
1b080 6f 72 2d 74 72 69 67 67 65 72 73 20 68 61 73 20  or-triggers has 
1b090 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20  been disabled - 
1b0a0 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 73 20 6e  0 if .** it is n
1b0b0 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
1b0c0 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 20 3c 2f  f it is.  .** </
1b0d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
1b0e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 45  TE_DBCONFIG_RESE
1b0f0 54 5f 44 41 54 41 42 41 53 45 5d 5d 20 3c 64 74  T_DATABASE]] <dt
1b100 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1b110 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 3c  _RESET_DATABASE<
1b120 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 53 65 74  /dt>.** <dd> Set
1b130 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
1b140 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42  NFIG_RESET_DATAB
1b150 41 53 45 20 66 6c 61 67 20 61 6e 64 20 74 68 65  ASE flag and the
1b160 6e 20 72 75 6e 0a 2a 2a 20 5b 56 41 43 55 55 4d  n run.** [VACUUM
1b170 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  ] in order to re
1b180 73 65 74 20 61 20 64 61 74 61 62 61 73 65 20 62  set a database b
1b190 61 63 6b 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ack to an empty 
1b1a0 64 61 74 61 62 61 73 65 0a 2a 2a 20 77 69 74 68  database.** with
1b1b0 20 6e 6f 20 73 63 68 65 6d 61 20 61 6e 64 20 6e   no schema and n
1b1c0 6f 20 63 6f 6e 74 65 6e 74 2e 20 54 68 65 20 66  o content. The f
1b1d0 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 63 65 73 73  ollowing process
1b1e0 20 77 6f 72 6b 73 20 65 76 65 6e 20 66 6f 72 0a   works even for.
1b1f0 2a 2a 20 61 20 62 61 64 6c 79 20 63 6f 72 72 75  ** a badly corru
1b200 70 74 65 64 20 64 61 74 61 62 61 73 65 20 66 69  pted database fi
1b210 6c 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  le:.** <ol>.** <
1b220 6c 69 3e 20 49 66 20 74 68 65 20 64 61 74 61 62  li> If the datab
1b230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1b240 73 20 6e 65 77 6c 79 20 6f 70 65 6e 65 64 2c 20  s newly opened, 
1b250 6d 61 6b 65 20 73 75 72 65 20 69 74 20 68 61 73  make sure it has
1b260 20 72 65 61 64 20 74 68 65 0a 2a 2a 20 20 20 20   read the.**    
1b270 20 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d    database schem
1b280 61 20 62 79 20 70 72 65 70 61 72 69 6e 67 20 74  a by preparing t
1b290 68 65 6e 20 64 69 73 63 61 72 64 69 6e 67 20 73  hen discarding s
1b2a0 6f 6d 65 20 71 75 65 72 79 20 61 67 61 69 6e 73  ome query agains
1b2b0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 64 61  t the.**      da
1b2c0 74 61 62 61 73 65 2c 20 6f 72 20 63 61 6c 6c 69  tabase, or calli
1b2d0 6e 67 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  ng sqlite3_table
1b2e0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
1b2f0 28 29 2c 20 69 67 6e 6f 72 69 6e 67 20 61 6e 79  (), ignoring any
1b300 0a 2a 2a 20 20 20 20 20 20 65 72 72 6f 72 73 2e  .**      errors.
1b310 20 20 54 68 69 73 20 73 74 65 70 20 69 73 20 6f    This step is o
1b320 6e 6c 79 20 6e 65 63 65 73 73 61 72 79 20 69 66  nly necessary if
1b330 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1b340 20 64 65 73 69 72 65 73 20 74 6f 20 6b 65 65 70   desires to keep
1b350 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 64 61 74  .**      the dat
1b360 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f 64  abase in WAL mod
1b370 65 20 61 66 74 65 72 20 74 68 65 20 72 65 73 65  e after the rese
1b380 74 20 69 66 20 69 74 20 77 61 73 20 69 6e 20 57  t if it was in W
1b390 41 4c 20 6d 6f 64 65 20 62 65 66 6f 72 65 0a 2a  AL mode before.*
1b3a0 2a 20 20 20 20 20 20 74 68 65 20 72 65 73 65 74  *      the reset
1b3b0 2e 20 20 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69  .  .** <li> sqli
1b3c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62  te3_db_config(db
1b3d0 2c 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  , SQLITE_DBCONFI
1b3e0 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45  G_RESET_DATABASE
1b3f0 2c 20 31 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e  , 1, 0);.** <li>
1b400 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 5d 28   [sqlite3_exec](
1b410 64 62 2c 20 22 5b 56 41 43 55 55 4d 5d 22 2c 20  db, "[VACUUM]", 
1b420 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69  0, 0, 0);.** <li
1b430 3e 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  > sqlite3_db_con
1b440 66 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44  fig(db, SQLITE_D
1b450 42 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41  BCONFIG_RESET_DA
1b460 54 41 42 41 53 45 2c 20 30 2c 20 30 29 3b 0a 2a  TABASE, 0, 0);.*
1b470 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 20 42 65 63 61 75  * </ol>.** Becau
1b480 73 65 20 72 65 73 65 74 74 69 6e 67 20 61 20 64  se resetting a d
1b490 61 74 61 62 61 73 65 20 69 73 20 64 65 73 74 72  atabase is destr
1b4a0 75 63 74 69 76 65 20 61 6e 64 20 69 72 72 65 76  uctive and irrev
1b4b0 65 72 73 69 62 6c 65 2c 20 74 68 65 0a 2a 2a 20  ersible, the.** 
1b4c0 70 72 6f 63 65 73 73 20 72 65 71 75 69 72 65 73  process requires
1b4d0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 69 73   the use of this
1b4e0 20 6f 62 73 63 75 72 65 20 41 50 49 20 61 6e 64   obscure API and
1b4f0 20 6d 75 6c 74 69 70 6c 65 20 73 74 65 70 73 20   multiple steps 
1b500 74 6f 20 68 65 6c 70 0a 2a 2a 20 65 6e 73 75 72  to help.** ensur
1b510 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e  e that it does n
1b520 6f 74 20 68 61 70 70 65 6e 20 62 79 20 61 63 63  ot happen by acc
1b530 69 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ident..**.** [[S
1b540 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44  QLITE_DBCONFIG_D
1b550 45 46 45 4e 53 49 56 45 5d 5d 20 3c 64 74 3e 53  EFENSIVE]] <dt>S
1b560 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 44  QLITE_DBCONFIG_D
1b570 45 46 45 4e 53 49 56 45 3c 2f 64 74 3e 0a 2a 2a  EFENSIVE</dt>.**
1b580 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f   <dd>The SQLITE_
1b590 44 42 43 4f 4e 46 49 47 5f 44 45 46 45 4e 53 49  DBCONFIG_DEFENSI
1b5a0 56 45 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61  VE option activa
1b5b0 74 65 73 20 6f 72 20 64 65 61 63 74 69 76 61 74  tes or deactivat
1b5c0 65 73 20 74 68 65 0a 2a 2a 20 22 64 65 66 65 6e  es the.** "defen
1b5d0 73 69 76 65 22 20 66 6c 61 67 20 66 6f 72 20 61  sive" flag for a
1b5e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b5f0 74 69 6f 6e 2e 20 20 57 68 65 6e 20 74 68 65 20  tion.  When the 
1b600 64 65 66 65 6e 73 69 76 65 0a 2a 2a 20 66 6c 61  defensive.** fla
1b610 67 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 6c 61  g is enabled, la
1b620 6e 67 75 61 67 65 20 66 65 61 74 75 72 65 73 20  nguage features 
1b630 74 68 61 74 20 61 6c 6c 6f 77 20 6f 72 64 69 6e  that allow ordin
1b640 61 72 79 20 53 51 4c 20 74 6f 20 0a 2a 2a 20 64  ary SQL to .** d
1b650 65 6c 69 62 65 72 61 74 65 6c 79 20 63 6f 72 72  eliberately corr
1b660 75 70 74 20 74 68 65 20 64 61 74 61 62 61 73 65  upt the database
1b670 20 66 69 6c 65 20 61 72 65 20 64 69 73 61 62 6c   file are disabl
1b680 65 64 2e 20 20 54 68 65 20 64 69 73 61 62 6c 65  ed.  The disable
1b690 64 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 69 6e  d.** features in
1b6a0 63 6c 75 64 65 20 62 75 74 20 61 72 65 20 6e 6f  clude but are no
1b6b0 74 20 6c 69 6d 69 74 65 64 20 74 6f 20 74 68 65  t limited to the
1b6c0 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a 2a 2a 20 3c   following:.** <
1b6d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
1b6e0 5b 50 52 41 47 4d 41 20 77 72 69 74 61 62 6c 65  [PRAGMA writable
1b6f0 5f 73 63 68 65 6d 61 3d 4f 4e 5d 20 73 74 61 74  _schema=ON] stat
1b700 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  ement..** <li> T
1b710 68 65 20 5b 50 52 41 47 4d 41 20 6a 6f 75 72 6e  he [PRAGMA journ
1b720 61 6c 5f 6d 6f 64 65 3d 4f 46 46 5d 20 73 74 61  al_mode=OFF] sta
1b730 74 65 6d 65 6e 74 2e 0a 2a 2a 20 3c 6c 69 3e 20  tement..** <li> 
1b740 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 5b 73  Writes to the [s
1b750 71 6c 69 74 65 5f 64 62 70 61 67 65 5d 20 76 69  qlite_dbpage] vi
1b760 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a 2a 2a 20  rtual table..** 
1b770 3c 6c 69 3e 20 44 69 72 65 63 74 20 77 72 69 74  <li> Direct writ
1b780 65 73 20 74 6f 20 5b 73 68 61 64 6f 77 20 74 61  es to [shadow ta
1b790 62 6c 65 73 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  bles]..** </ul>.
1b7a0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
1b7b0 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
1b7c0 5f 57 52 49 54 41 42 4c 45 5f 53 43 48 45 4d 41  _WRITABLE_SCHEMA
1b7d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ]] <dt>SQLITE_DB
1b7e0 43 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f  CONFIG_WRITABLE_
1b7f0 53 43 48 45 4d 41 3c 2f 64 74 3e 0a 2a 2a 20 3c  SCHEMA</dt>.** <
1b800 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 44 42  dd>The SQLITE_DB
1b810 43 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f  CONFIG_WRITABLE_
1b820 53 43 48 45 4d 41 20 6f 70 74 69 6f 6e 20 61 63  SCHEMA option ac
1b830 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74  tivates or deact
1b840 69 76 61 74 65 73 20 74 68 65 0a 2a 2a 20 22 77  ivates the.** "w
1b850 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 22 20  ritable_schema" 
1b860 66 6c 61 67 2e 20 54 68 69 73 20 68 61 73 20 74  flag. This has t
1b870 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20 61  he same effect a
1b880 6e 64 20 69 73 20 6c 6f 67 69 63 61 6c 6c 79 20  nd is logically 
1b890 65 71 75 69 76 61 6c 65 6e 74 0a 2a 2a 20 74 6f  equivalent.** to
1b8a0 20 73 65 74 74 69 6e 67 20 5b 50 52 41 47 4d 41   setting [PRAGMA
1b8b0 20 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61   writable_schema
1b8c0 3d 4f 4e 5d 20 6f 72 20 5b 50 52 41 47 4d 41 20  =ON] or [PRAGMA 
1b8d0 77 72 69 74 61 62 6c 65 5f 73 63 68 65 6d 61 3d  writable_schema=
1b8e0 4f 46 46 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  OFF]..** The fir
1b8f0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1b900 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 61  his setting is a
1b910 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
1b920 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
1b930 0a 2a 2a 20 74 68 65 20 77 72 69 74 61 62 6c 65  .** the writable
1b940 5f 73 63 68 65 6d 61 2c 20 70 6f 73 69 74 69 76  _schema, positiv
1b950 65 20 74 6f 20 65 6e 61 62 6c 65 20 77 72 69 74  e to enable writ
1b960 61 62 6c 65 5f 73 63 68 65 6d 61 2c 20 6f 72 20  able_schema, or 
1b970 6e 65 67 61 74 69 76 65 20 74 6f 0a 2a 2a 20 6c  negative to.** l
1b980 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
1b990 20 75 6e 63 68 61 6e 67 65 64 2e 20 54 68 65 20   unchanged. The 
1b9a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1b9b0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1b9c0 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69   an.** integer i
1b9d0 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 72 69  nto which is wri
1b9e0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
1b9f0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
1ba00 74 68 65 20 77 72 69 74 61 62 6c 65 5f 73 63 68  the writable_sch
1ba10 65 6d 61 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65  ema.** is enable
1ba20 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f  d or disabled fo
1ba30 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
1ba40 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  l..** </dd>.**.*
1ba50 2a 20 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  * [[SQLITE_DBCON
1ba60 46 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54 45 52  FIG_LEGACY_ALTER
1ba70 5f 54 41 42 4c 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  _TABLE]].** <dt>
1ba80 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1ba90 4c 45 47 41 43 59 5f 41 4c 54 45 52 5f 54 41 42  LEGACY_ALTER_TAB
1baa0 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  LE</dt>.** <dd>T
1bab0 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
1bac0 49 47 5f 4c 45 47 41 43 59 5f 41 4c 54 45 52 5f  IG_LEGACY_ALTER_
1bad0 54 41 42 4c 45 20 6f 70 74 69 6f 6e 20 61 63 74  TABLE option act
1bae0 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69  ivates or deacti
1baf0 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 6c 65 67  vates.** the leg
1bb00 61 63 79 20 62 65 68 61 76 69 6f 72 20 6f 66 20  acy behavior of 
1bb10 74 68 65 20 5b 41 4c 54 45 52 20 54 41 42 4c 45  the [ALTER TABLE
1bb20 20 52 45 4e 41 4d 45 5d 20 63 6f 6d 6d 61 6e 64   RENAME] command
1bb30 20 73 75 63 68 20 69 74 0a 2a 2a 20 62 65 68 61   such it.** beha
1bb40 76 65 73 20 61 73 20 69 74 20 64 69 64 20 70 72  ves as it did pr
1bb50 69 6f 72 20 74 6f 20 5b 76 65 72 73 69 6f 6e 20  ior to [version 
1bb60 33 2e 32 34 2e 30 5d 20 28 32 30 31 38 2d 30 36  3.24.0] (2018-06
1bb70 2d 30 34 29 2e 20 20 53 65 65 20 74 68 65 0a 2a  -04).  See the.*
1bb80 2a 20 22 43 6f 6d 70 61 74 69 62 69 6c 69 74 79  * "Compatibility
1bb90 20 4e 6f 74 69 63 65 22 20 6f 6e 20 74 68 65 20   Notice" on the 
1bba0 5b 41 4c 54 45 52 20 54 41 42 4c 45 20 52 45 4e  [ALTER TABLE REN
1bbb0 41 4d 45 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  AME documentatio
1bbc0 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  n] for.** additi
1bbd0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1bbe0 2e 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63  . This feature c
1bbf0 61 6e 20 61 6c 73 6f 20 62 65 20 74 75 72 6e 65  an also be turne
1bc00 64 20 6f 6e 20 61 6e 64 20 6f 66 66 0a 2a 2a 20  d on and off.** 
1bc10 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  using the [PRAGM
1bc20 41 20 6c 65 67 61 63 79 5f 61 6c 74 65 72 5f 74  A legacy_alter_t
1bc30 61 62 6c 65 5d 20 73 74 61 74 65 6d 65 6e 74 2e  able] statement.
1bc40 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1bc50 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
1bc60 47 5f 4e 4f 5f 44 51 53 5f 53 43 48 45 4d 41 5d  G_NO_DQS_SCHEMA]
1bc70 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
1bc80 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 44 51 53 5f  DBCONFIG_NO_DQS_
1bc90 53 43 48 45 4d 41 3c 2f 74 64 3e 0a 2a 2a 20 3c  SCHEMA</td>.** <
1bca0 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 44 42  dd>The SQLITE_DB
1bcb0 43 4f 4e 46 49 47 5f 4e 4f 5f 44 51 53 5f 53 43  CONFIG_NO_DQS_SC
1bcc0 48 45 4d 41 20 6f 70 74 69 6f 6e 20 61 63 74 69  HEMA option acti
1bcd0 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69 76  vates or deactiv
1bce0 61 74 65 73 0a 2a 2a 20 74 68 65 20 6c 65 67 61  ates.** the lega
1bcf0 63 79 20 5b 64 6f 75 62 6c 65 2d 71 75 6f 74 65  cy [double-quote
1bd00 64 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  d string literal
1bd10 5d 20 6d 69 73 66 65 61 74 75 72 65 20 66 6f 72  ] misfeature for
1bd20 20 44 44 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   DDL statements.
1bd30 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1bd40 5b 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  [[SQLITE_DBCONFI
1bd50 47 5f 4e 4f 5f 44 51 53 5d 5d 0a 2a 2a 20 3c 64  G_NO_DQS]].** <d
1bd60 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1bd70 47 5f 4e 4f 5f 44 51 53 3c 2f 74 64 3e 0a 2a 2a  G_NO_DQS</td>.**
1bd80 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f   <dd>The SQLITE_
1bd90 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 44 51 53 20  DBCONFIG_NO_DQS 
1bda0 6f 70 74 69 6f 6e 20 61 63 74 69 76 61 74 65 73  option activates
1bdb0 20 6f 72 20 64 65 61 63 74 69 76 61 74 65 73 0a   or deactivates.
1bdc0 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 5b 64  ** the legacy [d
1bdd0 6f 75 62 6c 65 2d 71 75 6f 74 65 64 20 73 74 72  ouble-quoted str
1bde0 69 6e 67 20 6c 69 74 65 72 61 6c 5d 20 6d 69 73  ing literal] mis
1bdf0 66 65 61 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  feature.  The.**
1be00 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 64 20 73   double-quoted s
1be10 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 6d 69  tring literal mi
1be20 73 66 65 61 74 75 72 65 20 69 73 20 6f 6e 20 62  sfeature is on b
1be30 79 20 64 65 66 61 75 6c 74 20 66 6f 72 0a 2a 2a  y default for.**
1be40 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
1be50 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
1be60 62 65 63 6f 6d 65 20 6f 66 66 20 62 79 20 64 65  become off by de
1be70 66 61 75 6c 74 20 69 6e 20 73 6f 6d 65 0a 2a 2a  fault in some.**
1be80 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
1be90 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 3c 2f  of SQLite..** </
1bea0 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
1beb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1bec0 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41  BCONFIG_MAINDBNA
1bed0 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 31 30  ME            10
1bee0 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72  00 /* const char
1bef0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1bf00 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
1bf10 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20  KASIDE          
1bf20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a     1001 /* void*
1bf30 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
1bf40 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1bf50 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
1bf60 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f            1002 /
1bf70 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1bf80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1bf90 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
1bfa0 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33  GGER        1003
1bfb0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1bfc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1bfd0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
1bfe0 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30  TS3_TOKENIZER 10
1bff0 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  04 /* int int* *
1c000 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c010 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1c020 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
1c030 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1005 /* int int*
1c040 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c050 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
1c060 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20  KPT_ON_CLOSE    
1c070 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e    1006 /* int in
1c080 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1c090 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1c0a0 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20 20 20  ABLE_QPSG       
1c0b0 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e 74 20      1007 /* int 
1c0c0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1c0d0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1c0e0 54 52 49 47 47 45 52 5f 45 51 50 20 20 20 20 20  TRIGGER_EQP     
1c0f0 20 20 20 20 20 20 31 30 30 38 20 2f 2a 20 69 6e        1008 /* in
1c100 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1c110 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1c120 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45  G_RESET_DATABASE
1c130 20 20 20 20 20 20 20 20 31 30 30 39 20 2f 2a 20          1009 /* 
1c140 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1c150 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1c160 46 49 47 5f 44 45 46 45 4e 53 49 56 45 20 20 20  FIG_DEFENSIVE   
1c170 20 20 20 20 20 20 20 20 20 20 31 30 31 30 20 2f            1010 /
1c180 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1c190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1c1a0 4f 4e 46 49 47 5f 57 52 49 54 41 42 4c 45 5f 53  ONFIG_WRITABLE_S
1c1b0 43 48 45 4d 41 20 20 20 20 20 20 20 31 30 31 31  CHEMA       1011
1c1c0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1c1d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c1e0 42 43 4f 4e 46 49 47 5f 4c 45 47 41 43 59 5f 41  BCONFIG_LEGACY_A
1c1f0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 31 30  LTER_TABLE    10
1c200 31 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  12 /* int int* *
1c210 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c220 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 44 51 53  _DBCONFIG_NO_DQS
1c230 5f 53 43 48 45 4d 41 20 20 20 20 20 20 20 20 20  _SCHEMA         
1c240 31 30 31 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1013 /* int int*
1c250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c260 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 44  TE_DBCONFIG_NO_D
1c270 51 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20  QS              
1c280 20 20 31 30 31 34 20 2f 2a 20 69 6e 74 20 69 6e    1014 /* int in
1c290 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
1c2a0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
1c2b0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  X               
1c2c0 20 20 20 20 31 30 31 34 20 2f 2a 20 4c 61 72 67      1014 /* Larg
1c2d0 65 73 74 20 44 42 43 4f 4e 46 49 47 20 2a 2f 0a  est DBCONFIG */.
1c2e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c2f0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
1c300 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
1c310 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
1c320 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c330 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1c340 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
1c350 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
1c360 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
1c370 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
1c380 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
1c390 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
1c3a0 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
1c3b0 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
1c3c0 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
1c3d0 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
1c3e0 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
1c3f0 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
1c400 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1c410 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
1c420 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
1c430 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
1c440 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
1c450 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44   Rowid.** METHOD
1c460 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1c470 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
1c480 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
1c490 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
1c4a0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
1c4b0 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
1c4c0 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
1c4d0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
1c4e0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
1c4f0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
1c500 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
1c510 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
1c520 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
1c530 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
1c540 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
1c550 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
1c560 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
1c570 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
1c580 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
1c590 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
1c5a0 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
1c5b0 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
1c5c0 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
1c5d0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
1c5e0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
1c5f0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
1c600 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
1c610 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
1c620 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1c630 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
1c640 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65  rface usually re
1c650 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
1c660 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74  ] of.** the most
1c670 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
1c680 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
1c690 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
1c6a0 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
1c6b0 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
1c6c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e   connection D. ^
1c6d0 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
1c6e0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
1c6f0 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  les are not.** r
1c700 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20  ecorded. ^If no 
1c710 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
1c720 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
1c730 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72  tables have ever
1c740 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e   occurred .** on
1c750 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1c760 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e  nnection D, then
1c770 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1c780 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
1c790 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a  turns .** zero..
1c7a0 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73  **.** As well as
1c7b0 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d   being set autom
1c7c0 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73  atically as rows
1c7d0 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e   are inserted in
1c7e0 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74  to database.** t
1c7f0 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65  ables, the value
1c800 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
1c810 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  s function may b
1c820 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79  e set explicitly
1c830 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
1c840 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1c850 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53  rowid()].**.** S
1c860 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ome virtual tabl
1c870 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1c880 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77  s may INSERT row
1c890 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
1c8a0 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  les as.** part o
1c8b0 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74  f committing a t
1c8c0 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e  ransaction (e.g.
1c8d0 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61   to flush data a
1c8e0 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65  ccumulated in me
1c8f0 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29  mory.** to disk)
1c900 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73  . In this case s
1c910 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1c920 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
1c930 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69   return the rowi
1c940 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  d.** associated 
1c950 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72  with these inter
1c960 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61  nal INSERT opera
1c970 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61  tions, which lea
1c980 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75  ds to .** unintu
1c990 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56  itive results. V
1c9a0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
1c9b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61  lementations tha
1c9c0 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f  t do write to ro
1c9d0 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e  wid.** tables in
1c9e0 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76   this way can av
1c9f0 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d  oid this problem
1ca00 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68   by restoring th
1ca10 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72  e original .** r
1ca20 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67  owid value using
1ca30 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
1ca40 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1ca50 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  )] before return
1ca60 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20  ing .** control 
1ca70 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a  to the user..**.
1ca80 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
1ca90 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
1caa0 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e  n a trigger then
1cab0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1cac0 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ll .** return th
1cad0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
1cae0 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73   inserted row as
1caf0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
1cb00 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e  gger is .** runn
1cb10 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72  ing. Once the tr
1cb20 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e  igger program en
1cb30 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
1cb40 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
1cb50 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
1cb60 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
1cb70 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
1cb80 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29  gger was fired.)
1cb90 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
1cba0 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
1cbb0 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
1cbc0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
1cbd0 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
1cbe0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
1cbf0 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
1cc00 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
1cc10 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
1cc20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
1cc30 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
1cc40 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
1cc50 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
1cc60 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
1cc70 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
1cc80 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
1cc90 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1cca0 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
1ccb0 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
1ccc0 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
1ccd0 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
1cce0 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
1ccf0 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
1cd00 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
1cd10 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
1cd20 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
1cd30 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
1cd40 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
1cd50 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
1cd60 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
1cd70 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
1cd80 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
1cd90 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
1cda0 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
1cdb0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
1cdc0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1cdd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
1cde0 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
1cdf0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
1ce00 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
1ce10 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
1ce20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
1ce30 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
1ce40 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
1ce50 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
1ce60 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
1ce70 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
1ce80 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
1ce90 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
1cea0 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
1ceb0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1cec0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1ced0 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
1cee0 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
1cef0 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
1cf00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
1cf10 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
1cf20 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1cf30 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
1cf40 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
1cf50 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
1cf60 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1cf70 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
1cf80 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1cf90 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
1cfa0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
1cfb0 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
1cfc0 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
1cfd0 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
1cfe0 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
1cff0 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
1d000 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
1d010 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1d020 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1d030 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
1d040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d050 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49  : Set the Last I
1d060 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75  nsert Rowid valu
1d070 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  e..** METHOD: sq
1d080 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
1d090 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1d0a0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c  _insert_rowid(D,
1d0b0 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77   R) method allow
1d0c0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
1d0d0 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20  n to.** set the 
1d0e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1d0f0 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  y calling sqlite
1d100 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1d110 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20  wid(D) to R .** 
1d120 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e  without insertin
1d130 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65  g a row into the
1d140 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f   database..*/.vo
1d150 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  id sqlite3_set_l
1d160 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1d170 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65  (sqlite3*,sqlite
1d180 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
1d190 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
1d1a0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
1d1b0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1d1c0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1d1d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1d1e0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1d1f0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1d200 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
1d210 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
1d220 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
1d230 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
1d240 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1d250 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
1d260 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
1d270 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d280 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1d290 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1d2a0 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
1d2b0 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1d2c0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
1d2d0 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
1d2e0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
1d2f0 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
1d300 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
1d310 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1d320 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
1d330 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1d340 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1d350 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
1d360 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
1d370 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
1d380 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
1d390 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
1d3a0 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
1d3b0 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
1d3c0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1d3d0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1d3e0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1d3f0 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
1d400 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1d410 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1d420 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
1d430 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
1d440 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
1d450 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
1d460 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
1d470 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1d480 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
1d490 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
1d4a0 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1d4b0 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
1d4c0 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
1d4d0 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
1d4e0 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
1d4f0 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
1d500 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
1d510 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1d520 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
1d530 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
1d540 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1d550 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
1d560 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
1d570 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
1d580 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
1d590 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
1d5a0 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
1d5b0 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
1d5c0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1d5d0 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
1d5e0 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
1d5f0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
1d600 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
1d610 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
1d620 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
1d630 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1d640 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
1d650 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
1d660 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
1d670 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1d680 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
1d690 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1d6a0 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
1d6b0 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1d6c0 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
1d6d0 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
1d6e0 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
1d6f0 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
1d700 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
1d710 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
1d720 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
1d730 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
1d740 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
1d750 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
1d760 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
1d770 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1d780 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1d790 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
1d7a0 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
1d7b0 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
1d7c0 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
1d7d0 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
1d7e0 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
1d7f0 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
1d800 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
1d810 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1d820 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
1d830 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
1d840 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
1d850 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
1d860 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
1d870 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
1d880 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
1d890 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
1d8a0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
1d8b0 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
1d8c0 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
1d8d0 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
1d8e0 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1d8f0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1d900 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
1d910 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1d920 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
1d930 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
1d940 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
1d950 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
1d960 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
1d970 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
1d980 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
1d990 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1d9a0 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
1d9b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1d9c0 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
1d9d0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
1d9e0 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
1d9f0 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
1da00 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1da10 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1da20 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
1da30 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  rigger..**.** If
1da40 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1da50 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1da60 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1da70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1da80 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1da90 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
1daa0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1dab0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1dac0 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
1dad0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1dae0 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ningful..**.** S
1daf0 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 6c 3e  ee also:.** <ul>
1db00 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 73 71  .** <li> the [sq
1db10 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1db20 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1db30 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f  .** <li> the [co
1db40 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1db50 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  ma].** <li> the 
1db60 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1db70 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e  unction].** <li>
1db80 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69   the [data_versi
1db90 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 2f  on pragma].** </
1dba0 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul>.*/.int sqlit
1dbb0 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
1dbc0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1dbd0 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
1dbe0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1dbf0 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
1dc00 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1dc10 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1dc20 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
1dc30 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
1dc40 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64  serted, modified
1dc50 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
1dc60 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20  y all [INSERT], 
1dc70 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
1dc80 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
1dc90 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e  completed.** sin
1dca0 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
1dcb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f  connection was o
1dcc0 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67  pened, including
1dcd0 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20   those executed 
1dce0 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72  as.** part of tr
1dcf0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
1dd00 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1dd10 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1dd20 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f   statement.** do
1dd30 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68  es not affect th
1dd40 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1dd50 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
1dd60 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20  l_changes()..** 
1dd70 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64  .** ^Changes mad
1dd80 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f  e as part of [fo
1dd90 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
1dda0 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  s] are included 
1ddb0 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c  in the.** count,
1ddc0 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20   but those made 
1ddd0 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41  as part of REPLA
1dde0 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  CE constraint re
1ddf0 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20  solution are.** 
1de00 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f  not. ^Changes to
1de10 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1de20 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1de30 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1de40 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ers .** are not 
1de50 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
1de60 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
1de70 6c 5f 63 68 61 6e 67 65 73 28 44 29 5d 20 69 6e  l_changes(D)] in
1de80 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70  terface only rep
1de90 6f 72 74 73 20 74 68 65 20 6e 75 6d 62 65 72 0a  orts the number.
1dea0 2a 2a 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20  ** of rows that 
1deb0 63 68 61 6e 67 65 64 20 64 75 65 20 74 6f 20 53  changed due to S
1dec0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  QL statement run
1ded0 20 61 67 61 69 6e 73 74 20 64 61 74 61 62 61 73   against databas
1dee0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
1def0 44 2e 20 20 41 6e 79 20 63 68 61 6e 67 65 73 20  D.  Any changes 
1df00 62 79 20 6f 74 68 65 72 20 64 61 74 61 62 61 73  by other databas
1df10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 72  e connections ar
1df20 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 54 6f  e ignored..** To
1df30 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 73 20   detect changes 
1df40 61 67 61 69 6e 73 74 20 61 20 64 61 74 61 62 61  against a databa
1df50 73 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f 74 68  se file from oth
1df60 65 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  er database.** c
1df70 6f 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65 20 74  onnections use t
1df80 68 65 20 5b 50 52 41 47 4d 41 20 64 61 74 61 5f  he [PRAGMA data_
1df90 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 6e 64  version] command
1dfa0 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   or the.** [SQLI
1dfb0 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45  TE_FCNTL_DATA_VE
1dfc0 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e  RSION] [file con
1dfd0 74 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  trol]..** .** If
1dfe0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1dff0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1e000 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1e010 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e020 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1e030 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1e040 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1e050 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
1e060 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
1e070 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1e080 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1e090 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 0a 2a  *.** See also:.*
1e0a0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74  * <ul>.** <li> t
1e0b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
1e0c0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1e0d0 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b 63 6f  .** <li> the [co
1e0e0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1e0f0 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20  ma].** <li> the 
1e100 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1e110 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c 69 3e  unction].** <li>
1e120 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 73 69   the [data_versi
1e130 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 3c 6c  on pragma].** <l
1e140 69 3e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  i> the [SQLITE_F
1e150 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 49 4f  CNTL_DATA_VERSIO
1e160 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  N] [file control
1e170 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ].** </ul>.*/.in
1e180 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
1e190 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1e1a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e1b0 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
1e1c0 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
1e1d0 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ry.** METHOD: sq
1e1e0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1e1f0 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
1e200 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
1e210 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1e220 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
1e230 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
1e240 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
1e250 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
1e260 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
1e270 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
1e280 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
1e290 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
1e2a0 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
1e2b0 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
1e2c0 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
1e2d0 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
1e2e0 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
1e2f0 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
1e300 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
1e310 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1e320 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
1e330 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
1e340 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
1e350 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
1e360 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
1e370 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
1e380 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
1e390 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
1e3a0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1e3b0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1e3c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
1e3d0 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
1e3e0 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
1e3f0 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
1e400 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
1e410 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
1e420 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1e430 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
1e440 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
1e450 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
1e460 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
1e470 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
1e480 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
1e490 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
1e4a0 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
1e4b0 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
1e4c0 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
1e4d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
1e4e0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
1e4f0 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
1e500 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
1e510 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
1e520 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
1e530 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
1e540 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
1e550 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
1e560 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
1e570 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
1e580 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
1e590 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
1e5a0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
1e5b0 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
1e5c0 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
1e5d0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
1e5e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1e5f0 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
1e600 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
1e610 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1e620 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1e630 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
1e640 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
1e650 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
1e660 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1e670 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1e680 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1e690 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1e6a0 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
1e6b0 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
1e6c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
1e6d0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
1e6e0 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
1e6f0 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
1e700 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
1e710 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1e720 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1e730 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
1e740 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1e750 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1e760 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
1e770 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
1e780 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
1e790 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
1e7a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1e7b0 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
1e7c0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1e7d0 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
1e7e0 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
1e7f0 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
1e800 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1e810 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
1e820 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
1e830 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
1e840 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1e850 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1e860 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1e870 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
1e880 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ns..*/.void sqli
1e890 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
1e8a0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1e8b0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
1e8c0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
1e8d0 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
1e8e0 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
1e8f0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
1e900 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
1e910 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
1e920 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
1e930 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
1e940 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
1e950 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
1e960 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1e970 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
1e980 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
1e990 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
1e9a0 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
1e9b0 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
1e9c0 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
1e9d0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1e9e0 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
1e9f0 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
1ea00 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
1ea10 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
1ea20 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
1ea30 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
1ea40 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
1ea50 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
1ea60 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
1ea70 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
1ea80 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
1ea90 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
1eaa0 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
1eab0 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
1eac0 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
1ead0 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
1eae0 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
1eaf0 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
1eb00 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
1eb10 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
1eb20 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
1eb30 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
1eb40 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
1eb50 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
1eb60 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
1eb70 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
1eb80 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
1eb90 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
1eba0 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
1ebb0 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
1ebc0 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
1ebd0 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
1ebe0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
1ebf0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1ec00 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
1ec10 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
1ec20 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
1ec30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ec40 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
1ec50 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
1ec60 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
1ec70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
1ec80 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
1ec90 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
1eca0 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
1ecb0 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
1ecc0 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
1ecd0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
1ece0 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
1ecf0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
1ed00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
1ed10 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
1ed20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
1ed30 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1ed40 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
1ed50 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
1ed60 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
1ed70 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
1ed80 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1ed90 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
1eda0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
1edb0 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
1edc0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1edd0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1ede0 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
1edf0 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
1ee00 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1ee10 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
1ee20 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
1ee30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
1ee40 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1ee50 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
1ee60 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1ee70 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
1ee80 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
1ee90 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1eea0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
1eeb0 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1eec0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1eed0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
1eee0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1eef0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1ef00 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
1ef10 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
1ef20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1ef30 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
1ef40 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
1ef50 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
1ef60 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
1ef70 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
1ef80 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  Errors.** KEYWOR
1ef90 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65  DS: {busy-handle
1efa0 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73  r callback} {bus
1efb0 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45  y handler}.** ME
1efc0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1efd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1efe0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c  _busy_handler(D,
1eff0 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74  X,P) routine set
1f000 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1f010 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20  ction X.** that 
1f020 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1f030 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
1f040 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
1f050 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
1f060 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61  to access a data
1f070 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63  base table assoc
1f080 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64  iated with.** [d
1f090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f0a0 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68  on] D when anoth
1f0b0 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
1f0c0 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20  process has the 
1f0d0 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  table locked..**
1f0e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73   The sqlite3_bus
1f0f0 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65  y_handler() inte
1f100 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
1f110 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73   implement.** [s
1f120 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1f130 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47  out()] and [PRAG
1f140 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
1f150 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1f160 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1f170 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
1f180 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20  ITE_BUSY].** is 
1f190 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1f1a0 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
1f1b0 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
1f1c0 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
1f1d0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
1f1e0 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
1f1f0 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
1f200 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
1f210 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
1f220 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1f230 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1f240 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1f250 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
1f260 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
1f270 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
1f280 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
1f290 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1f2a0 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
1f2b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
1f2c0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1f2d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1f2e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
1f2f0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
1f300 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
1f310 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65  been invoked pre
1f320 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20  viously for the 
1f330 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65  same locking eve
1f340 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
1f350 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
1f360 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
1f370 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
1f380 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
1f390 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
1f3a0 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
1f3b0 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74  ITE_BUSY] is ret
1f3c0 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  urned.** to the 
1f3d0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20  application..** 
1f3e0 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
1f3f0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1f400 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
1f410 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
1f420 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  de to access the
1f430 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68   database and th
1f440 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
1f450 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
1f460 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
1f470 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
1f480 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
1f490 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
1f4a0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
1f4b0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
1f4c0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
1f4d0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
1f4e0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
1f4f0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
1f500 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
1f510 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
1f520 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
1f530 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
1f540 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1f550 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f  cation instead o
1f560 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a  f invoking the .
1f570 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  ** busy handler.
1f580 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
1f590 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
1f5a0 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
1f5b0 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
1f5c0 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
1f5d0 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
1f5e0 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
1f5f0 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
1f600 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
1f610 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
1f620 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
1f630 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
1f640 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
1f650 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
1f660 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1f670 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
1f680 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
1f690 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
1f6a0 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
1f6b0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
1f6c0 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
1f6d0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1f6e0 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
1f6f0 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
1f700 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
1f710 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1f720 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
1f730 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
1f740 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
1f750 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
1f760 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
1f770 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
1f780 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
1f790 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
1f7a0 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
1f7b0 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
1f7c0 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
1f7d0 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
1f7e0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1f7f0 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
1f800 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1f810 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
1f820 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   NULL..**.** ^(T
1f830 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1f840 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1f850 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
1f860 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
1f870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1f880 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
1f890 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
1f8a0 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
1f8b0 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
1f8c0 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
1f8d0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
1f8e0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1f8f0 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74  )].** or evaluat
1f900 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79  ing [PRAGMA busy
1f910 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c  _timeout=N] will
1f920 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62   change the.** b
1f930 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20  usy handler and 
1f940 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70  thus clear any p
1f950 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75  reviously set bu
1f960 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
1f970 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
1f980 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
1f990 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
1f9a0 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
1f9b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1f9c0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1f9d0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1f9e0 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72  ndler.  In other
1f9f0 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62   words,.** the b
1fa00 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e  usy handler is n
1fa10 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41  ot reentrant.  A
1fa20 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
1fa30 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
1fa40 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
1fa50 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
1fa60 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1fa70 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
1fa80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1fa90 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
1faa0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
1fab0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1fac0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
1fad0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1fae0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74  ler(sqlite3*,int
1faf0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76  (*)(void*,int),v
1fb00 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1fb10 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1fb20 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45  sy Timeout.** ME
1fb30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1fb40 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1fb50 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1fb60 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1fb70 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1fb80 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1fb90 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1fba0 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1fbb0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1fbc0 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1fbd0 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1fbe0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1fbf0 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1fc00 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1fc10 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1fc20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1fc30 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1fc40 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1fc50 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1fc60 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1fc70 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1fc80 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1fc90 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1fca0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1fcb0 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1fcc0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1fcd0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1fce0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1fcf0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1fd00 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1fd10 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1fd20 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1fd30 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1fd40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1fd50 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1fd60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1fd70 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1fd80 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1fd90 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1fda0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1fdb0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1fdc0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1fdd0 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1fde0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1fdf0 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1fe00 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1fe10 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1fe20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1fe30 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1fe40 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
1fe50 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1fe60 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1fe70 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1fe80 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1fe90 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1fea0 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1feb0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1fec0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
1fed0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1fee0 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
1fef0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
1ff00 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1ff10 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
1ff20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
1ff30 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
1ff40 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
1ff50 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
1ff60 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
1ff70 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
1ff80 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
1ff90 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1ffa0 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
1ffb0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
1ffc0 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
1ffd0 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
1ffe0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
1fff0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
20000 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
20010 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
20020 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
20030 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
20040 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
20050 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
20060 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
20070 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
20080 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
20090 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
200a0 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
200b0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
200c0 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
200d0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
200e0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
200f0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
20100 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
20110 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
20120 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
20130 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
20140 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
20150 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
20160 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
20170 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
20180 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
20190 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
201a0 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
201b0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
201c0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
201d0 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
201e0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
201f0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
20200 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
20210 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
20220 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
20230 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
20240 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
20250 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
20260 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
20270 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
20280 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
20290 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
202a0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
202b0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
202c0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
202d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
202e0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
202f0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
20300 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
20310 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
20320 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
20330 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
20340 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
20350 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
20360 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
20370 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
20380 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
20390 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
203a0 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
203b0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
203c0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
203d0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
203e0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
203f0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
20400 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
20410 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
20420 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
20430 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
20440 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
20450 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
20460 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
20470 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
20480 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
20490 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
204a0 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
204b0 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
204c0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
204d0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
204e0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
204f0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
20500 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
20510 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
20520 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
20530 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
20540 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
20550 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
20560 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
20570 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
20580 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
20590 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
205a0 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
205b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
205c0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
205d0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
205e0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
205f0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
20600 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
20610 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
20620 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
20630 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
20640 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
20650 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
20660 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
20670 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
20680 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
20690 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
206a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
206b0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
206c0 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
206d0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
206e0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
206f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
20700 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
20710 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
20720 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
20730 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
20740 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
20750 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
20760 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
20770 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
20780 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
20790 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
207a0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
207b0 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
207c0 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
207d0 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
207e0 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
207f0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
20800 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
20810 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
20820 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
20830 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
20840 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
20850 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
20860 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
20870 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
20880 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
20890 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
208a0 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
208b0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
208c0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
208d0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
208e0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
208f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
20900 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
20910 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
20920 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
20930 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
20940 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
20950 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
20960 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
20970 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
20980 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
20990 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
209a0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
209b0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
209c0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
209d0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
209e0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
209f0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
20a00 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
20a10 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
20a20 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
20a30 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
20a40 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
20a50 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
20a60 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
20a70 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
20a80 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
20a90 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
20aa0 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
20ab0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
20ac0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
20ad0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
20ae0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
20af0 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
20b00 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
20b10 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
20b20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
20b30 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
20b40 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
20b50 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
20b60 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
20b70 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
20b80 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
20b90 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
20ba0 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
20bb0 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
20bc0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
20bd0 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
20be0 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
20bf0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
20c00 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
20c10 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
20c20 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
20c30 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
20c40 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
20c50 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
20c60 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
20c70 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
20c80 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
20c90 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
20ca0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
20cb0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
20cc0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
20cd0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
20ce0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
20cf0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
20d00 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
20d10 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
20d20 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65   library..** The
20d30 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65  se routines unde
20d40 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74  rstand most of t
20d50 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f 72 6d 61 74  he common format
20d60 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f  ting options fro
20d70 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
20d80 64 20 6c 69 62 72 61 72 79 20 70 72 69 6e 74 66  d library printf
20d90 28 29 20 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65  () .** plus some
20da0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d   additional non-
20db0 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73  standard formats
20dc0 20 28 5b 25 71 5d 2c 20 5b 25 51 5d 2c 20 5b 25   ([%q], [%Q], [%
20dd0 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d 29 2e 0a 2a  w], and [%z])..*
20de0 2a 20 53 65 65 20 74 68 65 20 5b 62 75 69 6c 74  * See the [built
20df0 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 20 64 6f  -in printf()] do
20e00 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
20e10 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  details..**.** ^
20e20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
20e30 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
20e40 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
20e50 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
20e60 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
20e70 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
20e80 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
20e90 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e 0a 2a 2a 20  malloc64()]..** 
20ea0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
20eb0 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
20ec0 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
20ed0 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
20ee0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
20ef0 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
20f00 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
20f10 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
20f20 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
20f30 63 36 34 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  c64()] is unable
20f40 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
20f50 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
20f60 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
20f70 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
20f80 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
20f90 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
20fa0 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
20fb0 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
20fc0 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
20fd0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
20fe0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
20ff0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
21000 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
21010 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
21020 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
21030 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
21040 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
21050 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
21060 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
21070 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
21080 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
21090 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
210a0 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
210b0 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
210c0 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
210d0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
210e0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
210f0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
21100 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
21110 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
21120 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
21130 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
21140 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
21150 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
21160 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
21170 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
21180 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
21190 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
211a0 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
211b0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
211c0 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
211d0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
211e0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
211f0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
21200 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
21210 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
21220 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
21230 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
21240 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
21250 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
21260 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
21270 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
21280 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
21290 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
212a0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
212b0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
212c0 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
212d0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
212e0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
212f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
21300 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
21310 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
21320 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
21330 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
21340 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
21350 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
21360 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
21370 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
21380 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
21390 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
213a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
213b0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
213c0 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
213d0 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
213e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
213f0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
21400 6f 3a 20 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72  o:  [built-in pr
21410 69 6e 74 66 28 29 5d 2c 20 5b 70 72 69 6e 74 66  intf()], [printf
21420 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
21430 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
21440 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
21450 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
21460 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
21470 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
21480 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
21490 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
214a0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
214b0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
214c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
214d0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
214e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
214f0 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
21500 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
21510 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
21520 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
21530 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
21540 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
21550 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
21560 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
21570 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
21580 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
21590 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
215a0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
215b0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
215c0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
215d0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
215e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
215f0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
21600 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
21610 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
21620 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
21630 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
21640 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
21650 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
21660 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
21670 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
21680 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
21690 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
216a0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
216b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
216c0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
216d0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
216e0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
216f0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
21700 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
21710 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
21720 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
21730 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
21740 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
21750 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
21760 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
21770 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
21780 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
21790 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
217a0 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
217b0 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
217c0 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
217d0 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
217e0 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
217f0 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
21800 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
21810 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
21820 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
21830 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
21840 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
21850 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
21860 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
21870 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
21880 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
21890 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
218a0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
218b0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
218c0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
218d0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
218e0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
218f0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
21900 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
21910 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
21920 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
21930 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
21940 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
21950 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
21960 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
21970 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
21980 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
21990 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
219a0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
219b0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
219c0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
219d0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
219e0 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
219f0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
21a00 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
21a10 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
21a20 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
21a30 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
21a40 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
21a50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
21a60 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
21a70 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
21a80 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
21a90 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
21aa0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
21ab0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
21ac0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
21ad0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
21ae0 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
21af0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
21b00 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
21b10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
21b20 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
21b30 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
21b40 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
21b50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
21b60 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
21b70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
21b80 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
21b90 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
21ba0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
21bb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
21bc0 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
21bd0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
21be0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
21bf0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
21c00 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
21c10 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
21c20 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
21c30 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
21c40 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
21c50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
21c60 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
21c70 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
21c80 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
21c90 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
21ca0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
21cb0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
21cc0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
21cd0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
21ce0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
21cf0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
21d00 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
21d10 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
21d20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
21d30 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
21d40 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
21d50 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
21d60 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
21d70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
21d80 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
21d90 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
21da0 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
21db0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
21dc0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
21dd0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
21de0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
21df0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
21e00 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
21e10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
21e20 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
21e30 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
21e40 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
21e50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
21e60 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
21e70 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
21e80 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
21e90 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
21ea0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
21eb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
21ec0 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
21ed0 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
21ee0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
21ef0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
21f00 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
21f10 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
21f20 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
21f30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
21f40 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
21f50 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
21f60 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
21f70 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
21f80 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
21f90 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
21fa0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
21fb0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
21fc0 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
21fd0 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
21fe0 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
21ff0 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
22000 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
22010 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
22020 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
22030 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
22040 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
22050 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
22060 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
22070 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
22080 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
22090 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
220a0 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
220b0 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
220c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
220d0 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
220e0 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
220f0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
22100 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
22110 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
22120 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
22130 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
22140 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
22150 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
22160 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
22170 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
22180 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
22190 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
221a0 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
221b0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
221c0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
221d0 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
221e0 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
221f0 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
22200 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
22210 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
22220 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
22230 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
22240 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
22250 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
22260 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
22270 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
22280 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
22290 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
222a0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
222b0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
222c0 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
222d0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
222e0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
222f0 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
22300 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
22310 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
22320 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
22330 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
22340 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
22350 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
22360 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
22370 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
22380 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
22390 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
223a0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
223b0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
223c0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
223d0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
223e0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
223f0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
22400 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
22410 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
22420 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
22430 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
22440 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
22450 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
22460 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
22470 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
22480 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
22490 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
224a0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
224b0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
224c0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
224d0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
224e0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
224f0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
22500 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
22510 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
22520 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
22530 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
22540 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
22550 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
22560 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
22570 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
22580 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
22590 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
225a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
225b0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
225c0 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
225d0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
225e0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
225f0 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
22600 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
22610 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
22620 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
22630 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
22640 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
22650 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
22660 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
22670 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
22680 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
22690 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
226a0 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
226b0 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  t64);.void *sqli
226c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
226d0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  *, int);.void *s
226e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
226f0 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f  (void*, sqlite3_
22700 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  uint64);.void sq
22710 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
22720 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  );.sqlite3_uint6
22730 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
22740 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
22750 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
22760 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
22770 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
22780 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
22790 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
227a0 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
227b0 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
227c0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
227d0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
227e0 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
227f0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
22800 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
22810 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
22820 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
22830 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
22840 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
22850 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
22860 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
22870 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
22880 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
22890 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
228a0 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
228b0 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
228c0 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
228d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
228e0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
228f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
22900 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
22910 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
22920 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
22930 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
22940 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
22950 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
22960 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
22970 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
22980 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
22990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
229a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
229b0 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
229c0 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
229d0 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
229e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
229f0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
22a00 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
22a10 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
22a20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
22a30 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
22a40 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
22a50 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
22a60 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
22a70 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
22a80 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
22a90 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
22aa0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
22ab0 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
22ac0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
22ad0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
22ae0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
22af0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
22b00 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
22b10 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
22b20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
22b30 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
22b40 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
22b50 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
22b60 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
22b70 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
22b80 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
22b90 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
22ba0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
22bb0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
22bc0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
22bd0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
22be0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
22bf0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
22c00 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
22c10 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
22c20 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
22c30 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
22c40 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
22c50 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
22c60 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
22c70 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
22c80 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
22c90 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
22ca0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
22cb0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
22cc0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
22cd0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
22ce0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
22cf0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
22d00 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
22d10 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
22d20 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
22d30 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
22d40 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
22d50 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
22d60 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
22d70 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
22d80 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
22d90 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
22da0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
22db0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
22dc0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
22dd0 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
22de0 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
22df0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
22e00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
22e10 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
22e20 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
22e30 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
22e40 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
22e50 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
22e60 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
22e70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
22e80 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
22e90 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
22ea0 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
22eb0 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
22ec0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
22ed0 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
22ee0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
22ef0 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
22f00 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
22f10 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
22f20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
22f30 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
22f40 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
22f50 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
22f60 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
22f70 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
22f80 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
22f90 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
22fa0 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
22fb0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
22fc0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
22fd0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
22fe0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
22ff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
23000 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
23010 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
23020 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
23030 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44  lite3.** KEYWORD
23040 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63  S: {authorizer c
23050 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e  allback}.**.** ^
23060 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
23070 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
23080 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
23090 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
230a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
230b0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
230c0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
230d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
230e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
230f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
23100 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
23110 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
23120 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
23130 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
23140 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
23150 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23160 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
23170 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
23180 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
23190 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  are16()], [sqlit
231a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
231b0 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  )],.** and [sqli
231c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
231d0 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
231e0 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
231f0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
23200 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
23210 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
23220 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
23230 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
23240 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
23250 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
23260 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
23270 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
23280 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
23290 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
232a0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
232b0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
232c0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
232d0 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
232e0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
232f0 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
23300 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
23310 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
23320 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
23330 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
23340 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
23350 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
23360 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
23370 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
23380 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
23390 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
233a0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
233b0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
233c0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
233d0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
233e0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
233f0 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
23400 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
23410 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
23420 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
23430 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
23440 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
23450 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
23460 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
23470 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
23480 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
23490 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
234a0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
234b0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
234c0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
234d0 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
234e0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
234f0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
23500 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
23510 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23520 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
23530 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
23540 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
23550 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
23560 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
23570 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
23580 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
23590 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
235a0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
235b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
235c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
235d0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
235e0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
235f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
23600 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
23610 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
23620 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
23630 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
23640 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
23650 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
23660 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
23670 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
23680 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
23690 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
236a0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
236b0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
236c0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
236d0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
236e0 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68  allback are eith
236f0 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  er NULL pointers
23700 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   or zero-termina
23710 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74  ted strings.** t
23720 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
23730 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
23740 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
23750 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
23760 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
23770 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65  s must always be
23780 20 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63   prepared to enc
23790 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f  ounter a NULL po
237a0 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20  inter in any.** 
237b0 6f 66 20 74 68 65 20 74 68 69 72 64 20 74 68 72  of the third thr
237c0 6f 75 67 68 20 74 68 65 20 73 69 78 74 68 20 70  ough the sixth p
237d0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
237e0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
237f0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
23800 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
23810 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
23820 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
23830 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
23840 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
23850 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
23860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23870 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
23880 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
23890 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
238a0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
238b0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
238c0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
238d0 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
238e0 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
238f0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
23900 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
23910 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
23920 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
23930 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
23940 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
23950 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
23960 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
23970 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ble..** ^When a 
23980 74 61 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e  table is referen
23990 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54  ced by a [SELECT
239a0 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20  ] but no column 
239b0 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78  values are.** ex
239c0 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61  tracted from tha
239d0 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61  t table (for exa
239e0 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20  mple in a query 
239f0 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20  like.** "SELECT 
23a00 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61  count(*) FROM ta
23a10 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51  b") then the [SQ
23a20 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f  LITE_READ] autho
23a30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
23a40 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  * is invoked onc
23a50 65 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65  e for that table
23a60 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e   with a column n
23a70 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20 65  ame that is an e
23a80 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  mpty string..** 
23a90 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
23aa0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
23ab0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
23ac0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
23ad0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
23ae0 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
23af0 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
23b00 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
23b10 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
23b20 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
23b30 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
23b40 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
23b50 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
23b60 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
23b70 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
23b80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
23b90 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
23ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
23bb0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
23bc0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
23bd0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
23be0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
23bf0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
23c00 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
23c10 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
23c20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
23c30 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
23c40 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
23c50 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
23c60 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
23c70 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
23c80 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
23c90 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
23ca0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
23cb0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
23cc0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
23cd0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
23ce0 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
23cf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
23d00 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
23d10 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
23d20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
23d30 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
23d40 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
23d50 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
23d60 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
23d70 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
23d80 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
23d90 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
23da0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
23db0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
23dc0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
23dd0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
23de0 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
23df0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
23e00 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
23e10 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
23e20 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
23e30 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
23e40 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
23e50 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
23e60 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
23e70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
23e80 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
23e90 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
23ea0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
23eb0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
23ec0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
23ed0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
23ee0 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
23ef0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
23f00 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
23f10 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
23f20 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
23f30 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
23f40 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
23f50 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
23f60 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
23f70 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
23f80 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
23f90 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
23fa0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
23fb0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
23fc0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
23fd0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
23fe0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
23ff0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
24000 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
24010 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
24020 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
24030 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
24040 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
24050 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
24060 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
24070 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
24080 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24090 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
240a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
240b0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
240c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
240d0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
240e0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
240f0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
24100 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
24110 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
24120 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
24130 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
24140 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
24150 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
24160 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
24170 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
24180 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
24190 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
241a0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
241b0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
241c0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
241d0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
241e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
241f0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
24200 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
24210 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
24220 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
24230 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
24240 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
24250 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
24260 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
24270 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
24280 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
24290 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
242a0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
242b0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
242c0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
242d0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
242e0 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
242f0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
24300 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
24310 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
24320 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
24330 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
24340 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
24350 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
24360 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
24370 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
24380 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
24390 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
243a0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
243b0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
243c0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
243d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
243e0 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
243f0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
24400 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
24410 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
24420 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
24430 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
24440 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
24450 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
24460 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
24470 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
24480 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
24490 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
244a0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
244b0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
244c0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
244d0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
244e0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
244f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
24500 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
24510 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
24520 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
24530 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
24540 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
24550 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
24560 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
24570 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
24580 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
24590 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
245a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
245b0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
245c0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
245d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
245e0 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
245f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
24600 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
24610 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24620 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
24630 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
24640 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
24650 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
24660 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
24670 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
24680 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
24690 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
246a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
246b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
246c0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
246d0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
246e0 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
246f0 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
24700 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
24710 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
24720 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
24730 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
24740 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
24750 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
24760 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
24770 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
24780 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
24790 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
247a0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
247b0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
247c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
247d0 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
247e0 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
247f0 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
24800 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
24810 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
24820 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
24830 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
24840 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
24850 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
24860 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
24870 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
24880 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
24890 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
248a0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
248b0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
248c0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
248d0 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
248e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
248f0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
24900 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
24910 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
24920 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
24930 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
24940 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
24950 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
24960 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
24970 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
24980 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
24990 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
249a0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
249b0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
249c0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
249d0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
249e0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
249f0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
24a00 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
24a10 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
24a20 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
24a30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24a40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24a50 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
24a60 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
24a70 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
24a80 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
24a90 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
24aa0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
24ab0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
24ac0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24ad0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
24ae0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
24af0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24b00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24b10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24b20 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
24b30 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
24b40 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
24b50 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24b60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24b70 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
24b80 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
24b90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
24ba0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24bb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24bc0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
24bd0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
24be0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
24bf0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24c00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24c10 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
24c20 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
24c30 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
24c40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24c50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24c60 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
24c70 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
24c80 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
24c90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
24ca0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24cb0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
24cc0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
24cd0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
24ce0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24cf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24d00 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
24d10 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
24d20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
24d30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24d40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
24d50 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
24d60 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
24d70 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
24d80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
24d90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
24da0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
24db0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
24dc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
24dd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
24de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
24df0 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
24e00 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
24e10 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
24e20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
24e30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
24e40 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
24e50 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
24e60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
24e70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24e80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
24e90 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
24ea0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
24eb0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
24ec0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
24ed0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
24ee0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
24ef0 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
24f00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
24f10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24f20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
24f30 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
24f40 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
24f50 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
24f60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24f70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
24f80 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
24f90 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
24fa0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
24fb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24fc0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
24fd0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
24fe0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24ff0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
25000 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
25010 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
25020 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
25030 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
25040 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
25050 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
25060 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
25070 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
25080 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
25090 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
250a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
250b0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
250c0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
250d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
250e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
250f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
25100 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
25110 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
25120 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
25130 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
25140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25150 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
25160 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
25170 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
25180 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
25190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
251a0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
251b0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
251c0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
251d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
251e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
251f0 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
25200 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
25210 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
25220 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
25230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
25240 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
25250 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
25260 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
25270 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
25280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
25290 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
252a0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
252b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
252c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
252d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
252e0 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
252f0 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
25300 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
25310 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
25320 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
25330 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
25340 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
25350 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
25360 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
25370 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
25380 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
25390 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
253a0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
253b0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
253c0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
253d0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
253e0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
253f0 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
25400 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
25410 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
25420 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
25430 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
25440 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
25450 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
25460 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
25470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
25480 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
25490 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
254a0 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
254b0 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
254c0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
254d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
254e0 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
254f0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
25500 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
25510 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
25520 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
25530 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
25540 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 55  re deprecated. U
25550 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
25560 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65  trace_v2()] inte
25570 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64  rface.** instead
25580 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73   of the routines
25590 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 2e   described here.
255a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
255b0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
255c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
255d0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
255e0 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
255f0 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
25600 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
25610 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
25620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
25630 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
25640 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
25650 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
25660 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
25670 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
25680 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
25690 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
256a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
256b0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
256c0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
256d0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
256e0 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
256f0 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
25700 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
25710 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
25720 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
25730 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
25740 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
25750 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
25760 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
25770 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
25780 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
25790 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
257a0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
257b0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
257c0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
257d0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
257e0 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
257f0 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
25800 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
25810 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
25820 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
25830 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
25840 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
25850 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
25860 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
25870 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
25880 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
25890 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
258a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
258b0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
258c0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
258d0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
258e0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
258f0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
25900 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
25910 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
25920 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
25930 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
25940 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
25950 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
25960 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
25970 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
25980 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
25990 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
259a0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
259b0 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
259c0 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
259d0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
259e0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
259f0 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
25a00 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
25a10 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
25a20 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
25a30 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
25a40 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
25a50 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
25a60 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
25a70 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
25a80 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
25a90 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
25aa0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
25ab0 63 6b 2e 20 20 49 6e 76 6f 6b 69 6e 67 0a 2a 2a  ck.  Invoking.**
25ac0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
25ad0 5f 74 72 61 63 65 28 29 5d 20 6f 72 20 5b 73 71  _trace()] or [sq
25ae0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
25af0 5d 20 77 69 6c 6c 20 63 61 6e 63 65 6c 20 74 68  ] will cancel th
25b00 65 0a 2a 2a 20 70 72 6f 66 69 6c 65 20 63 61 6c  e.** profile cal
25b10 6c 62 61 63 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45  lback..*/.SQLITE
25b20 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
25b30 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
25b40 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
25b50 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
25b60 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
25b70 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  oid*);.SQLITE_DE
25b80 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
25b90 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
25ba0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
25bb0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
25bc0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
25bd0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
25be0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
25bf0 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63  PI3REF: SQL Trac
25c00 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a  e Event Codes.**
25c10 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
25c20 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68  E_TRACE.**.** Th
25c30 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64  ese constants id
25c40 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f  entify classes o
25c50 66 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61  f events that ca
25c60 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a  n be monitored.*
25c70 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  * using the [sql
25c80 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
25c90 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20   tracing logic. 
25ca0 20 54 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a   The M argument.
25cb0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ** to [sqlite3_t
25cc0 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29  race_v2(D,M,X,P)
25cd0 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f  ] is an OR-ed co
25ce0 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65  mbination of one
25cf0 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74   or more of.** t
25d00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
25d10 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69  stants.  ^The fi
25d20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
25d30 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
25d40 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20  ck.** is one of 
25d50 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
25d60 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e  nstants..**.** N
25d70 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74  ew tracing const
25d80 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65  ants may be adde
25d90 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
25da0 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  ases..**.** ^A t
25db0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61  race callback ha
25dc0 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73  s four arguments
25dd0 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  : xCallback(T,C,
25de0 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
25df0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
25e00 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74  of the integer t
25e10 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e  ype codes above.
25e20 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d  .** ^The C argum
25e30 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ent is a copy of
25e40 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69   the context poi
25e50 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61  nter passed in a
25e60 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
25e70 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
25e80 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
25e90 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
25ea0 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
25eb0 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
25ec0 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
25ed0 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a   T..**.** <dl>.*
25ee0 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
25ef0 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49  _STMT]] <dt>SQLI
25f00 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64  TE_TRACE_STMT</d
25f10 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
25f20 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
25f30 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
25f40 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61  ked when a prepa
25f50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
25f60 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75   first begins ru
25f70 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62  nning and possib
25f80 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65  ly at other time
25f90 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  s during the.** 
25fa0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
25fb0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25fc0 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20  ent, such as at 
25fd0 74 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63  the start of eac
25fe0 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62  h.** trigger sub
25ff0 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20  program. ^The P 
26000 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
26010 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
26020 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26030 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67  ent]. ^The X arg
26040 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
26050 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  er to a string w
26060 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75  hich.** is the u
26070 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65  nexpanded SQL te
26080 78 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  xt of the prepar
26090 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20  ed statement or 
260a0 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a  an SQL comment .
260b0 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
260c0 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e  s the invocation
260d0 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20   of a trigger.  
260e0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61  ^The callback ca
260f0 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65  n compute.** the
26100 20 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20   same text that 
26110 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20  would have been 
26120 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
26130 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
26140 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65  trace()].** inte
26150 72 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74  rface by using t
26160 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68  he X argument wh
26170 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68  en X begins with
26180 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69   "--" and invoki
26190 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
261a0 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20  xpanded_sql(P)] 
261b0 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
261c0 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
261d0 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51  PROFILE]] <dt>SQ
261e0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
261f0 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  LE</dt>.** <dd>^
26200 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
26210 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b  PROFILE callback
26220 20 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78   provides approx
26230 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65  imately the same
26240 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
26250 61 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  as is provided b
26260 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  y the [sqlite3_p
26270 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61  rofile()] callba
26280 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  ck..** ^The P ar
26290 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
262a0 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70  ter to the [prep
262b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
262c0 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67  and the.** X arg
262d0 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20  ument points to 
262e0 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  a 64-bit integer
262f0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73   which is the es
26300 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68  timated of.** th
26310 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
26320 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20  second that the 
26330 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26340 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a  nt took to run..
26350 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54  ** ^The SQLITE_T
26360 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
26370 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
26380 20 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   when the statem
26390 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
263a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
263b0 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c  CE_ROW]] <dt>SQL
263c0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64  ITE_TRACE_ROW</d
263d0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
263e0 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63  LITE_TRACE_ROW c
263f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
26400 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72  ed whenever a pr
26410 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
26420 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20  ent generates a 
26430 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65  single row of re
26440 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20  sult.  .** ^The 
26450 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
26460 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
26470 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26480 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
26490 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
264a0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  sed..**.** [[SQL
264b0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d  ITE_TRACE_CLOSE]
264c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
264d0 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  CE_CLOSE</dt>.**
264e0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
264f0 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c  TRACE_CLOSE call
26500 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
26510 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a  when a database.
26520 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  ** connection cl
26530 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  oses..** ^The P 
26540 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
26550 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
26560 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26570 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  n] object.** and
26580 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
26590 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f  is unused..** </
265a0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
265b0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
265c0 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66         0x01.#def
265d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
265e0 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32  _PROFILE    0x02
265f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26600 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20  TRACE_ROW       
26610 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51   0x04.#define SQ
26620 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
26630 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a        0x08../*.*
26640 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
26650 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45  Trace Hook.** ME
26660 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
26670 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26680 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c  _trace_v2(D,M,X,
26690 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  P) interface reg
266a0 69 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63  isters a trace c
266b0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
266c0 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64  ion X against [d
266d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
266e0 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f  on] D, using pro
266f0 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20  perty mask M.** 
26700 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  and context poin
26710 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20  ter P.  ^If the 
26720 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a  X callback is.**
26730 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20   NULL or if the 
26740 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20  M mask is zero, 
26750 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20  then tracing is 
26760 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a  disabled.  The.*
26770 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  * M argument sho
26780 75 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69  uld be the bitwi
26790 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61  se OR-ed combina
267a0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20  tion of.** zero 
267b0 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f  or more [SQLITE_
267c0 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73  TRACE] constants
267d0 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61  ..**.** ^Each ca
267e0 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c  ll to either sql
267f0 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
26800 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
26810 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a  () overrides .**
26820 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70   (cancels) any p
26830 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71  rior calls to sq
26840 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72  lite3_trace() or
26850 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
26860 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  2()..**.** ^The 
26870 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  X callback is in
26880 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
26890 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73  ny of the events
268a0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a   identified by .
268b0 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e  ** mask M occur.
268c0 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72    ^The integer r
268d0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
268e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
268f0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67   currently.** ig
26900 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68  nored, though th
26910 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e  is may change in
26920 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
26930 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  .  Callback.** i
26940 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
26950 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72  hould return zer
26960 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75  o to ensure futu
26970 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  re compatibility
26980 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65  ..**.** ^A trace
26990 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
269a0 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61  oked with four a
269b0 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61  rguments: callba
269c0 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20  ck(T,C,P,X)..** 
269d0 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20  ^The T argument 
269e0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53  is one of the [S
269f0 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20  QLITE_TRACE].** 
26a00 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64  constants to ind
26a10 69 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61  icate why the ca
26a20 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b  llback was invok
26a30 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72  ed..** ^The C ar
26a40 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79  gument is a copy
26a50 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20   of the context 
26a60 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20  pointer..** The 
26a70 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74  P and X argument
26a80 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77  s are pointers w
26a90 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65  hose meanings de
26aa0 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a  pend on T..**.**
26ab0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61   The sqlite3_tra
26ac0 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  ce_v2() interfac
26ad0 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  e is intended to
26ae0 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67   replace the leg
26af0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
26b00 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  s [sqlite3_trace
26b10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26b20 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74  _profile()], bot
26b30 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72  h of which.** ar
26b40 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f  e deprecated..*/
26b50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61  .int sqlite3_tra
26b60 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ce_v2(.  sqlite3
26b70 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d  *,.  unsigned uM
26b80 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c  ask,.  int(*xCal
26b90 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c  lback)(unsigned,
26ba0 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64  void*,void*,void
26bb0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78  *),.  void *pCtx
26bc0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
26bd0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
26be0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
26bf0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
26c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26c10 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
26c20 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
26c30 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
26c40 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
26c50 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
26c60 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
26c70 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
26c80 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
26c90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
26ca0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
26cb0 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
26cc0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
26cd0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
26ce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
26cf0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
26d00 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
26d10 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
26d20 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
26d30 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
26d40 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
26d50 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
26d60 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
26d70 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
26d80 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
26d90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
26da0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
26db0 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
26dc0 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
26dd0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
26de0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
26df0 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
26e00 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
26e10 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
26e20 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
26e30 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
26e40 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
26e50 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
26e60 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
26e70 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
26e80 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
26e90 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
26ea0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
26eb0 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
26ec0 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
26ed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
26ee0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
26ef0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
26f00 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
26f10 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
26f20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
26f30 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
26f40 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
26f50 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
26f60 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
26f70 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
26f80 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
26f90 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
26fa0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
26fb0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
26fc0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
26fd0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
26fe0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
26ff0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
27000 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
27010 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
27020 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
27030 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
27040 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
27050 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
27060 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
27070 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
27080 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
27090 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
270a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
270b0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
270c0 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
270d0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
270e0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
270f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
27100 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
27110 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
27120 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
27130 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
27140 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
27150 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
27160 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
27170 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
27180 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
27190 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
271a0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
271b0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
271c0 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
271d0 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
271e0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53  nnection.** CONS
271f0 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
27200 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
27210 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
27220 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
27230 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
27240 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
27250 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
27260 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
27270 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
27280 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
27290 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
272a0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
272b0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
272c0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
272d0 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
272e0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
272f0 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
27300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27310 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
27320 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
27330 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
27340 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
27350 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
27360 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
27370 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
27380 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
27390 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
273a0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
273b0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
273c0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
273d0 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
273e0 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
273f0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
27400 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
27410 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
27420 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
27430 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
27440 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
27450 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
27460 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
27470 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
27480 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
27490 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
274a0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
274b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
274c0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
274d0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
274e0 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
274f0 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
27500 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
27510 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
27520 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
27530 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
27540 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
27550 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
27560 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
27570 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
27580 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
27590 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
275a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
275b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
275c0 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
275d0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
275e0 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
275f0 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
27600 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
27610 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
27620 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
27630 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
27640 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
27650 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
27660 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
27670 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
27680 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
27690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
276a0 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
276b0 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
276c0 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
276d0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
276e0 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
276f0 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
27700 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
27710 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
27720 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
27730 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
27740 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
27750 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
27760 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
27770 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
27780 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
27790 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
277a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
277b0 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
277c0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
277d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
277e0 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
277f0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
27800 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
27810 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
27820 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
27830 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
27840 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
27850 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
27860 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
27870 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
27880 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
27890 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
278a0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
278b0 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
278c0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
278d0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
278e0 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
278f0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
27900 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
27910 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
27920 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
27930 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
27940 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
27950 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
27960 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
27970 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
27980 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
27990 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
279a0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
279b0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
279c0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
279d0 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
279e0 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
279f0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
27a00 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
27a10 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
27a20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
27a30 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
27a40 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
27a50 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
27a60 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
27a70 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
27a80 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
27a90 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
27aa0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
27ab0 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
27ac0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
27ad0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
27ae0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
27af0 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
27b00 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
27b10 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
27b20 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
27b30 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
27b40 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
27b50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
27b60 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
27b70 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
27b80 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
27b90 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
27ba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
27bb0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
27bc0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
27bd0 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
27be0 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
27bf0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
27c00 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
27c10 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
27c20 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
27c30 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
27c40 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
27c50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
27c60 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
27c70 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
27c80 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
27c90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27ca0 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
27cb0 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
27cc0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
27cd0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
27ce0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
27cf0 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
27d00 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
27d10 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
27d20 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
27d30 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
27d40 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
27d50 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
27d60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27d70 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
27d80 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
27d90 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
27da0 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
27db0 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
27dc0 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
27dd0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
27de0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
27df0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
27e00 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
27e10 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
27e20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27e30 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
27e40 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
27e50 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
27e60 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
27e70 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
27e80 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
27e90 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
27ea0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
27eb0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
27ec0 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
27ed0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
27ee0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
27ef0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
27f00 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
27f10 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
27f20 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
27f30 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
27f40 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
27f50 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
27f60 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27f70 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
27f80 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
27f90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
27fa0 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
27fb0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
27fc0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
27fd0 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
27fe0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
27ff0 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
28000 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
28010 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
28020 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
28030 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
28040 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
28050 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
28060 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
28070 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
28080 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
28090 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
280a0 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
280b0 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
280c0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
280d0 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
280e0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
280f0 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
28100 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
28110 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
28120 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
28130 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
28140 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
28150 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
28160 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
28170 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
28180 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
28190 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
281a0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
281b0 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
281c0 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
281d0 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
281e0 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
281f0 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
28200 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
28210 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
28220 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
28230 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
28240 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
28250 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
28260 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
28270 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
28280 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
28290 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
282a0 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
282b0 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
282c0 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
282d0 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
282e0 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
282f0 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
28300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28310 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
28320 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
28330 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
28340 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
28350 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
28360 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
28370 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
28380 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
28390 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
283a0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
283b0 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
283c0 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
283d0 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
283e0 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
283f0 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
28400 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
28410 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
28420 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
28430 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
28440 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 61 72   in the third ar
28450 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
28460 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
28470 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
28480 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
28490 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
284a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
284b0 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
284c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
284d0 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
284e0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
284f0 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
28500 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
28510 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
28520 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
28530 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
28540 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
28550 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
28560 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
28570 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
28580 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
28590 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
285a0 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
285b0 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
285c0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
285d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
285e0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
285f0 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
28600 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
28610 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
28620 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
28630 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
28640 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
28650 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
28660 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
28670 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
28680 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
28690 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
286a0 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
286b0 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
286c0 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
286d0 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
286e0 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
286f0 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
28700 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
28710 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
28720 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
28730 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
28740 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
28750 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
28760 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
28770 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
28780 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
28790 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
287a0 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
287b0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
287c0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
287d0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
287e0 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
287f0 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
28800 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
28810 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
28820 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
28830 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
28840 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
28850 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
28860 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
28870 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
28880 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
28890 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
288a0 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
288b0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
288c0 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
288d0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
288e0 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
288f0 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
28900 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
28910 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
28920 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
28930 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
28940 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
28950 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
28960 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
28970 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
28980 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
28990 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
289a0 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
289b0 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
289c0 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
289d0 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
289e0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
289f0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
28a00 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
28a10 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
28a20 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
28a30 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
28a40 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
28a50 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
28a60 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
28a70 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
28a80 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
28a90 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
28aa0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
28ab0 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
28ac0 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
28ad0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
28ae0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
28af0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
28b00 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
28b10 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
28b20 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
28b30 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
28b40 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
28b50 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
28b60 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
28b70 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
28b80 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
28b90 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
28ba0 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
28bb0 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
28bc0 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
28bd0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
28be0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
28bf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
28c00 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
28c10 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
28c20 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
28c30 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
28c40 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
28c50 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
28c60 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
28c70 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
28c80 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
28c90 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
28ca0 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
28cb0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
28cc0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
28cd0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
28ce0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
28cf0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
28d00 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
28d10 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
28d20 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
28d30 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
28d40 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
28d50 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
28d60 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
28d70 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
28d80 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
28d90 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
28da0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
28db0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
28dc0 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
28dd0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
28de0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
28df0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
28e00 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
28e10 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
28e20 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
28e30 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
28e40 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
28e50 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
28e60 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
28e70 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
28e80 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
28e90 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
28ea0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
28eb0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
28ec0 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
28ed0 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
28ee0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
28ef0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
28f00 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
28f10 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
28f20 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
28f30 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
28f40 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
28f50 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
28f60 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
28f70 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
28f80 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
28f90 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
28fa0 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
28fb0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
28fc0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
28fd0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
28fe0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
28ff0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
29000 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
29010 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
29020 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
29030 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
29040 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
29050 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
29060 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
29070 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
29080 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
29090 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
290a0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
290b0 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
290c0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
290d0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
290e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
290f0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
29100 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
29110 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
29120 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
29130 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
29140 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
29150 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
29160 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
29170 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
29180 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
29190 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
291a0 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
291b0 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
291c0 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
291d0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
291e0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
291f0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
29200 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
29210 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
29220 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
29230 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
29240 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
29250 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
29260 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
29270 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
29280 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
29290 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
292a0 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
292b0 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
292c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
292d0 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
292e0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
292f0 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
29300 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
29310 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
29320 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
29330 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
29340 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
29350 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
29360 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
29370 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
29380 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
29390 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
293a0 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
293b0 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
293c0 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
293d0 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
293e0 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
293f0 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
29400 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
29410 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
29420 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
29430 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
29440 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
29450 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
29460 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
29470 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
29480 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
29490 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
294a0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
294b0 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
294c0 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
294d0 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
294e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
294f0 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
29500 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
29510 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
29520 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
29530 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
29540 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
29550 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
29560 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
29570 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
29580 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
29590 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
295a0 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
295b0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
295c0 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
295d0 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
295e0 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
295f0 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
29600 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
29610 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
29620 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
29630 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
29640 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
29650 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
29660 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
29670 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
29680 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
29690 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
296a0 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
296b0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
296c0 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
296d0 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
296e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
296f0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
29700 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
29710 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
29720 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
29730 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
29740 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
29750 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
29760 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
29770 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
29780 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
29790 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
297a0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
297b0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
297c0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
297d0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
297e0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
297f0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
29800 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
29810 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
29820 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
29830 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
29840 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
29850 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
29860 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
29870 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
29880 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
29890 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
298a0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
298b0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
298c0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
298d0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
298e0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
298f0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
29900 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
29910 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
29920 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
29930 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
29940 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
29950 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
29960 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
29970 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
29980 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
29990 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
299a0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
299b0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
299c0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
299d0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
299e0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
299f0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
29a00 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
29a10 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
29a20 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
29a30 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
29a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
29a50 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
29a60 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
29a70 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
29a80 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
29a90 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
29aa0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
29ab0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
29ac0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
29ad0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
29ae0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
29af0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
29b00 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
29b10 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
29b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
29b30 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
29b40 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
29b50 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
29b60 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
29b70 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
29b80 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
29b90 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
29ba0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
29bb0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
29bc0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
29bd0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
29be0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
29bf0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
29c00 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
29c10 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
29c20 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
29c30 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
29c40 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
29c50 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
29c60 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
29c70 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
29c80 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
29c90 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
29ca0 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
29cb0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
29cc0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
29cd0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
29ce0 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
29cf0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
29d00 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
29d10 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
29d20 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
29d30 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
29d40 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
29d50 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
29d60 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
29d70 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
29d80 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
29d90 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
29da0 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
29db0 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
29dc0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
29dd0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
29de0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
29df0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
29e00 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
29e10 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
29e20 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
29e30 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
29e40 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
29e50 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
29e60 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
29e70 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
29e80 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
29e90 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
29ea0 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
29eb0 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
29ec0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
29ed0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
29ee0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
29ef0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
29f00 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
29f10 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
29f20 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
29f30 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
29f40 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
29f50 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
29f60 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
29f70 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
29f80 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
29f90 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
29fa0 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
29fb0 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
29fc0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
29fd0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
29fe0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
29ff0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
2a000 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
2a010 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
2a020 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
2a030 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
2a040 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
2a050 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
2a060 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
2a070 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
2a080 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
2a090 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
2a0a0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
2a0b0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
2a0c0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
2a0d0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
2a0e0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
2a0f0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
2a100 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
2a110 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
2a120 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
2a130 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
2a140 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
2a150 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
2a160 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
2a170 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
2a180 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
2a190 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
2a1a0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
2a1b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
2a1c0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
2a1d0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
2a1e0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
2a1f0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
2a200 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
2a210 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
2a220 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
2a230 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
2a240 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
2a250 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
2a260 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
2a270 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
2a280 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
2a290 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
2a2a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
2a2b0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
2a2c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2a2d0 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
2a2e0 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
2a2f0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
2a300 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
2a310 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
2a320 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
2a330 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
2a340 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
2a350 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2a360 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
2a370 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
2a380 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
2a390 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
2a3a0 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
2a3b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
2a3c0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
2a3d0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
2a3e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
2a3f0 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
2a400 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
2a410 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
2a420 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
2a430 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2a440 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
2a450 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
2a460 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
2a470 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
2a480 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
2a490 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
2a4a0 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
2a4b0 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
2a4c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
2a4d0 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
2a4e0 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
2a4f0 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
2a500 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
2a510 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
2a520 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
2a530 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
2a540 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
2a550 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
2a560 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
2a570 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
2a580 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
2a590 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
2a5a0 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
2a5b0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
2a5c0 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
2a5d0 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
2a5e0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
2a5f0 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
2a600 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
2a610 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
2a620 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2a630 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
2a640 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
2a650 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
2a660 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
2a670 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2a680 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
2a690 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
2a6a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
2a6b0 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
2a6c0 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
2a6d0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
2a6e0 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
2a6f0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
2a700 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
2a710 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
2a720 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
2a730 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
2a740 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
2a750 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
2a760 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
2a770 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
2a780 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
2a790 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
2a7a0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
2a7b0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
2a7c0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
2a7d0 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
2a7e0 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
2a7f0 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
2a800 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
2a810 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
2a820 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
2a830 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
2a840 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
2a850 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
2a860 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
2a870 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
2a880 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
2a890 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
2a8a0 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
2a8b0 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
2a8c0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
2a8d0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
2a8e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
2a8f0 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
2a900 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
2a910 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
2a920 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
2a930 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
2a940 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
2a950 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
2a960 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
2a970 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
2a980 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
2a990 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
2a9a0 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
2a9b0 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
2a9c0 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
2a9d0 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
2a9e0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
2a9f0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
2aa00 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
2aa10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2aa20 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
2aa30 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
2aa40 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
2aa50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
2aa60 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2aa70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
2aa80 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
2aa90 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
2aaa0 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
2aab0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
2aac0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2aad0 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
2aae0 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
2aaf0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
2ab00 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
2ab10 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
2ab20 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
2ab30 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
2ab40 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
2ab50 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
2ab60 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
2ab70 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
2ab80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
2ab90 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
2aba0 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
2abb0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
2abc0 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
2abd0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
2abe0 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
2abf0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2ac00 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
2ac10 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2ac20 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
2ac30 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
2ac40 53 65 65 20 74 68 65 20 5b 55 52 49 20 66 69 6c  See the [URI fil
2ac50 65 6e 61 6d 65 5d 20 64 6f 63 75 6d 65 6e 74 61  ename] documenta
2ac60 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
2ac70 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2ac80 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2ac90 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
2aca0 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
2acb0 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
2acc0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
2acd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  ;.int sqlite3_ur
2ace0 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
2acf0 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
2ad00 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
2ad10 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
2ad20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2ad30 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
2ad40 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
2ad50 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2ad60 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
2ad70 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
2ad80 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
2ad90 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ages.** METHOD: 
2ada0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49  sqlite3.**.** ^I
2adb0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2adc0 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  t sqlite3_* API 
2add0 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
2ade0 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61  with .** [databa
2adf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2ae00 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68   failed, then th
2ae10 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
2ae20 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  e(D) interface.*
2ae30 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * returns the nu
2ae40 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
2ae50 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
2ae60 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
2ae70 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61  r that.** API ca
2ae80 6c 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ll..** ^The sqli
2ae90 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
2aea0 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
2aeb0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
2aec0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
2aed0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
2aee0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
2aef0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
2af00 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
2af10 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
2af20 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
2af30 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 72  .** The values r
2af40 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2af50 65 33 5f 65 72 72 63 6f 64 65 28 29 20 61 6e 64  e3_errcode() and
2af60 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  /or.** sqlite3_e
2af70 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
2af80 29 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 77  ) might change w
2af90 69 74 68 20 65 61 63 68 20 41 50 49 20 63 61 6c  ith each API cal
2afa0 6c 2e 0a 2a 2a 20 45 78 63 65 70 74 2c 20 74 68  l..** Except, th
2afb0 65 72 65 20 61 72 65 20 73 6f 6d 65 20 69 6e 74  ere are some int
2afc0 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65  erfaces that are
2afd0 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 6e   guaranteed to n
2afe0 65 76 65 72 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ever.** change t
2aff0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2b000 65 72 72 6f 72 20 63 6f 64 65 2e 20 20 54 68 65  error code.  The
2b010 20 65 72 72 6f 72 2d 63 6f 64 65 20 70 72 65 73   error-code pres
2b020 65 72 76 69 6e 67 0a 2a 2a 20 69 6e 74 65 72 66  erving.** interf
2b030 61 63 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a 20  aces are:.**.** 
2b040 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c  <ul>.** <li> sql
2b050 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
2b060 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65  * <li> sqlite3_e
2b070 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
2b080 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65  ).** <li> sqlite
2b090 33 5f 65 72 72 6d 73 67 28 29 0a 2a 2a 20 3c 6c  3_errmsg().** <l
2b0a0 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  i> sqlite3_errms
2b0b0 67 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  g16().** </ul>.*
2b0c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b0d0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
2b0e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
2b0f0 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
2b100 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
2b110 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
2b120 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
2b130 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2b140 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
2b150 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
2b160 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
2b170 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
2b180 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
2b190 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
2b1a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
2b1b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
2b1c0 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
2b1d0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
2b1e0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
2b1f0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
2b200 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
2b210 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
2b220 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
2b230 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
2b240 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
2b250 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
2b260 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
2b270 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
2b280 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
2b290 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
2b2a0 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
2b2b0 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
2b2c0 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
2b2d0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
2b2e0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
2b2f0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
2b300 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
2b310 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
2b320 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
2b330 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b340 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
2b350 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
2b360 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
2b370 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
2b380 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
2b390 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
2b3a0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
2b3b0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
2b3c0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
2b3d0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
2b3e0 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
2b3f0 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
2b400 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
2b410 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
2b420 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
2b430 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
2b440 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
2b450 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
2b460 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
2b470 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
2b480 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
2b490 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
2b4a0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
2b4b0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
2b4c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2b4d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
2b4e0 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
2b4f0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
2b500 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
2b510 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
2b520 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
2b530 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
2b540 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
2b550 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
2b560 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
2b570 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
2b580 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
2b590 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
2b5a0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
2b5b0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
2b5c0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
2b5d0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
2b5e0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
2b5f0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
2b600 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
2b610 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
2b620 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
2b630 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
2b640 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
2b650 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
2b660 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
2b670 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
2b680 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
2b690 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
2b6a0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
2b6b0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
2b6c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2b6d0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
2b6e0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2b6f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
2b700 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
2b710 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
2b720 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
2b730 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70  * CAPI3REF: Prep
2b740 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2b750 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2b760 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
2b770 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
2b780 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
2b790 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
2b7a0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
2b7b0 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
2b7c0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
2b7d0 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65   that.** has bee
2b7e0 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  n compiled into 
2b7f0 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20  binary form and 
2b800 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65  is ready to be e
2b810 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  valuated..**.** 
2b820 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51  Think of each SQ
2b830 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61  L statement as a
2b840 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74   separate comput
2b850 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65  er program.  The
2b860 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2b870 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20   text is source 
2b880 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65  code.  A prepare
2b890 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
2b8a0 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f  ct .** is the co
2b8b0 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f  mpiled object co
2b8c0 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73  de.  All SQL mus
2b8d0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69  t be converted i
2b8e0 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65  nto a.** prepare
2b8f0 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f  d statement befo
2b900 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e  re it can be run
2b910 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
2b920 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70  -cycle of a prep
2b930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
2b940 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f  bject usually go
2b950 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  es like this:.**
2b960 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2b970 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70   Create the prep
2b980 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
2b990 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
2b9a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b9b0 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  )]..** <li> Bind
2b9c0 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61   values to [para
2b9d0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
2b9e0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2b9f0 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
2ba00 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
2ba10 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
2ba20 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
2ba30 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
2ba40 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
2ba50 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70  > Reset the prep
2ba60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2ba70 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
2ba80 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
2ba90 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
2baa0 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
2bab0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
2bac0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
2bad0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
2bae0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2baf0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
2bb00 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ol>.*/.typedef s
2bb10 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
2bb20 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
2bb30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bb40 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
2bb50 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
2bb60 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ite3.**.** ^(Thi
2bb70 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
2bb80 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
2bb90 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
2bba0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
2bbb0 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
2bbc0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
2bbd0 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
2bbe0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2bbf0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
2bc00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
2bc10 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
2bc20 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
2bc30 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
2bc40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
2bc50 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
2bc60 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
2bc70 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
2bc80 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
2bc90 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
2bca0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
2bcb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2bcc0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
2bcd0 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
2bce0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
2bcf0 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
2bd00 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
2bd10 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
2bd20 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
2bd30 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
2bd40 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
2bd50 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
2bd60 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
2bd70 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
2bd80 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
2bd90 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
2bda0 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
2bdb0 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
2bdc0 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
2bdd0 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
2bde0 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
2bdf0 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
2be00 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
2be10 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
2be20 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
2be30 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
2be40 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
2be50 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
2be60 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
2be70 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
2be80 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
2be90 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
2bea0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2beb0 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
2bec0 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
2bed0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
2bee0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
2bef0 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
2bf00 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
2bf10 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
2bf20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
2bf30 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
2bf40 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
2bf50 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
2bf60 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
2bf70 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
2bf80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2bf90 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
2bfa0 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
2bfb0 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
2bfc0 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
2bfd0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
2bfe0 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
2bff0 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
2c000 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
2c010 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
2c020 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
2c030 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
2c040 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
2c050 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
2c060 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
2c070 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
2c080 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
2c090 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
2c0a0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
2c0b0 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
2c0c0 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
2c0d0 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
2c0e0 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
2c0f0 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
2c100 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
2c110 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
2c120 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
2c130 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
2c140 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
2c150 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
2c160 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
2c170 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
2c180 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
2c190 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
2c1a0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
2c1b0 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
2c1c0 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
2c1d0 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
2c1e0 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
2c1f0 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
2c200 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
2c210 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
2c220 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
2c230 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
2c240 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
2c250 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
2c260 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
2c270 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
2c280 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
2c290 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
2c2a0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
2c2b0 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
2c2c0 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
2c2d0 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
2c2e0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
2c2f0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
2c300 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
2c310 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
2c320 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
2c330 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c340 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
2c350 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
2c360 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
2c370 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
2c380 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
2c390 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2c3a0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
2c3b0 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
2c3c0 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
2c3d0 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
2c3e0 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
2c3f0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
2c400 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
2c410 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
2c420 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
2c430 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
2c440 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
2c450 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2c460 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
2c470 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
2c480 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
2c490 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
2c4a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2c4b0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
2c4c0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2c4d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2c4e0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
2c4f0 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
2c500 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
2c510 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
2c520 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2c530 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2c540 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2c550 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2c560 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2c570 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
2c580 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
2c590 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
2c5a0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2c5b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
2c5c0 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
2c5d0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
2c5e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2c5f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2c600 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
2c610 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
2c620 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
2c630 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2c640 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
2c650 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
2c660 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
2c670 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
2c680 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
2c690 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
2c6a0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2c6b0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2c6c0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2c6d0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2c6e0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2c6f0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
2c700 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
2c710 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
2c720 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
2c730 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2c740 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
2c750 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2c760 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
2c770 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
2c780 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2c790 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
2c7a0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
2c7b0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
2c7c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2c7d0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2c7e0 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
2c7f0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
2c800 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2c810 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2c820 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
2c830 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
2c840 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
2c850 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
2c860 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2c870 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70  .  If [sqlite3_p
2c880 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
2c890 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  ** the equivalen
2c8a0 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63  t tries to alloc
2c8b0 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f  ate space for mo
2c8c0 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e  re than this man
2c8d0 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20  y opcodes.** in 
2c8e0 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65  a single prepare
2c8f0 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20  d statement, an 
2c900 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72  SQLITE_NOMEM err
2c910 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
2c920 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2c930 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2c940 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
2c950 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
2c960 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
2c970 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2c980 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
2c990 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
2c9a0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
2c9b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2c9c0 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
2c9d0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2c9e0 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
2c9f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2ca00 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
2ca10 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
2ca20 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
2ca30 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2ca40 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
2ca50 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
2ca60 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2ca70 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
2ca80 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
2ca90 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
2caa0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
2cab0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
2cac0 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
2cad0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2cae0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2caf0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
2cb00 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
2cb10 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
2cb20 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2cb30 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
2cb40 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
2cb50 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
2cb60 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
2cb70 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
2cb80 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
2cb90 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2cba0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
2cbb0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
2cbc0 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
2cbd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2cbe0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
2cbf0 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
2cc00 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
2cc10 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2cc20 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
2cc30 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2cc40 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
2cc50 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
2cc60 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2cc70 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
2cc80 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
2cc90 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
2cca0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ccb0 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
2ccc0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
2ccd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2cce0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
2ccf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2cd00 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
2cd10 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2cd20 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
2cd30 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2cd40 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2cd50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2cd60 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2cd70 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
2cd80 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
2cd90 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2cda0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2cdb0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
2cdc0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
2cdd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2cde0 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
2cdf0 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
2ce00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
2ce10 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
2ce20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
2ce30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
2ce40 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
2ce50 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
2ce60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2ce70 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2ce80 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
2ce90 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2cea0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2ceb0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
2cec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2ced0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
2cee0 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
2cef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2cf00 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2cf10 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
2cf20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cf30 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a  Prepare Flags.**
2cf40 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2cf50 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
2cf60 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63 61  us flags that ca
2cf70 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f  n be passed into
2cf80 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20  .** "prepFlags" 
2cf90 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2cfa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2cfb0 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  e_v3()] and.** [
2cfc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cfd0 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63  6_v3()] interfac
2cfe0 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c  es..**.** New fl
2cff0 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ags may be added
2d000 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
2d010 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
2d020 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
2d030 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2d040 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74  RSISTENT]] ^(<dt
2d050 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  >SQLITE_PREPARE_
2d060 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a  PERSISTENT</dt>.
2d070 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54  ** <dd>The SQLIT
2d080 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2d090 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68  TENT flag is a h
2d0a0 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72 79  int to the query
2d0b0 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74   planner.** that
2d0c0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2d0d0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
2d0e0 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c  retained for a l
2d0f0 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20  ong time and.** 
2d100 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20  probably reused 
2d110 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57  many times.)^ ^W
2d120 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67  ithout this flag
2d130 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
2d140 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20  re_v3()].** and 
2d150 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d160 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20  16_v3()] assume 
2d170 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
2d180 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  d statement will
2d190 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73   .** be used jus
2d1a0 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73  t once or at mos
2d1b0 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e  t a few times an
2d1c0 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64  d then destroyed
2d1d0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2d1e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72  e3_finalize()] r
2d1f0 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20  elatively soon. 
2d200 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  The current impl
2d210 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a  ementation acts.
2d220 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ** on this hint 
2d230 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20  by avoiding the 
2d240 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64  use of [lookasid
2d250 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20  e memory] so as 
2d260 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74  not to.** deplet
2d270 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74  e the limited st
2d280 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ore of lookaside
2d290 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20   memory. Future 
2d2a0 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53  versions of.** S
2d2b0 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e  QLite may act on
2d2c0 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 66 65   this hint diffe
2d2d0 72 65 6e 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  rently..**.** [[
2d2e0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2d2f0 4f 52 4d 41 4c 49 5a 45 5d 5d 20 3c 64 74 3e 53  ORMALIZE]] <dt>S
2d300 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f  QLITE_PREPARE_NO
2d310 52 4d 41 4c 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20  RMALIZE</dt>.** 
2d320 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50  <dd>The SQLITE_P
2d330 52 45 50 41 52 45 5f 4e 4f 52 4d 41 4c 49 5a 45  REPARE_NORMALIZE
2d340 20 66 6c 61 67 20 69 73 20 61 20 6e 6f 2d 6f 70   flag is a no-op
2d350 2e 20 54 68 69 73 20 66 6c 61 67 20 75 73 65 64  . This flag used
2d360 0a 2a 2a 20 74 6f 20 62 65 20 72 65 71 75 69 72  .** to be requir
2d370 65 64 20 66 6f 72 20 61 6e 79 20 70 72 65 70 61  ed for any prepa
2d380 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 68  red statement th
2d390 61 74 20 77 61 6e 74 65 64 20 74 6f 20 75 73 65  at wanted to use
2d3a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2d3b0 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2d3c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 48  )] interface.  H
2d3d0 6f 77 65 76 65 72 2c 20 74 68 65 0a 2a 2a 20 5b  owever, the.** [
2d3e0 73 71 6c 69 74 65 33 5f 6e 6f 72 6d 61 6c 69 7a  sqlite3_normaliz
2d3f0 65 64 5f 73 71 6c 28 29 5d 20 69 6e 74 65 72 66  ed_sql()] interf
2d400 61 63 65 20 69 73 20 6e 6f 77 20 61 76 61 69 6c  ace is now avail
2d410 61 62 6c 65 20 74 6f 20 61 6c 6c 0a 2a 2a 20 70  able to all.** p
2d420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d430 74 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ts, regardless o
2d440 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2d450 20 74 68 65 79 20 75 73 65 20 74 68 69 73 0a 2a   they use this.*
2d460 2a 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  * flag..**.** [[
2d470 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 4e  SQLITE_PREPARE_N
2d480 4f 5f 56 54 41 42 5d 5d 20 3c 64 74 3e 53 51 4c  O_VTAB]] <dt>SQL
2d490 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 5f 56  ITE_PREPARE_NO_V
2d4a0 54 41 42 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TAB</dt>.** <dd>
2d4b0 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  The SQLITE_PREPA
2d4c0 52 45 5f 4e 4f 5f 56 54 41 42 20 66 6c 61 67 20  RE_NO_VTAB flag 
2d4d0 63 61 75 73 65 73 20 74 68 65 20 53 51 4c 20 63  causes the SQL c
2d4e0 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 72 65  ompiler.** to re
2d4f0 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 28 65  turn an error (e
2d500 72 72 6f 72 20 63 6f 64 65 20 53 51 4c 49 54 45  rror code SQLITE
2d510 5f 45 52 52 4f 52 29 20 69 66 20 74 68 65 20 73  _ERROR) if the s
2d520 74 61 74 65 6d 65 6e 74 20 75 73 65 73 0a 2a 2a  tatement uses.**
2d530 20 61 6e 79 20 76 69 72 74 75 61 6c 20 74 61 62   any virtual tab
2d540 6c 65 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  les..** </dl>.*/
2d550 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d560 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2d570 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
2d580 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
2d590 49 54 45 5f 50 52 45 50 41 52 45 5f 4e 4f 52 4d  ITE_PREPARE_NORM
2d5a0 41 4c 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALIZE           
2d5b0 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65      0x02.#define
2d5c0 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2d5d0 4e 4f 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NO_VTAB         
2d5e0 20 20 20 20 20 20 20 20 30 78 30 34 0a 0a 2f 2a          0x04../*
2d5f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2d600 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
2d610 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
2d620 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
2d630 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
2d640 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2d650 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  3.** CONSTRUCTOR
2d660 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d670 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
2d680 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2d690 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
2d6a0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
2d6b0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
2d6c0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
2d6d0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2d6e0 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68  nes.  Or, in oth
2d6f0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20  er words, these 
2d700 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2d710 63 6f 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72  constructors for
2d720 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2d730 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
2d740 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66  ..**.** The pref
2d750 65 72 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f  erred routine to
2d760 20 75 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33   use is [sqlite3
2d770 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20  _prepare_v2()]. 
2d780 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
2d790 5f 70 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65  _prepare()] inte
2d7a0 72 66 61 63 65 20 69 73 20 6c 65 67 61 63 79 20  rface is legacy 
2d7b0 61 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76  and should be av
2d7c0 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74  oided..** [sqlit
2d7d0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2d7e0 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 22 70   has an extra "p
2d7f0 72 65 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e  repFlags" option
2d800 20 74 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a   that is used.**
2d810 20 66 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72   for special pur
2d820 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  poses..**.** The
2d830 20 75 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d   use of the UTF-
2d840 38 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  8 interfaces is 
2d850 70 72 65 66 65 72 72 65 64 2c 20 61 73 20 53 51  preferred, as SQ
2d860 4c 69 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a  Lite currently.*
2d870 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69  * does all parsi
2d880 6e 67 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20  ng using UTF-8. 
2d890 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65   The UTF-16 inte
2d8a0 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
2d8b0 64 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76  ded.** as a conv
2d8c0 65 6e 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54  enience.  The UT
2d8d0 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20  F-16 interfaces 
2d8e0 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69  work by converti
2d8f0 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20  ng the.** input 
2d900 74 65 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c  text into UTF-8,
2d910 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74   then invoking t
2d920 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2d930 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65   UTF-8 interface
2d940 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2d950 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
2d960 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
2d970 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
2d980 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
2d990 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
2d9a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d9b0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2d9c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
2d9d0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
2d9e0 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
2d9f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2da00 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
2da10 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
2da20 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
2da30 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
2da40 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
2da50 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
2da60 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
2da70 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2da80 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
2da90 74 65 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73  te3_prepare(), s
2daa0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2dab0 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  2(),.** and sqli
2dac0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2dad0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
2dae0 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
2daf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2db00 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2db10 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  re16_v2(),.** an
2db20 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2db30 65 31 36 5f 76 33 28 29 20 75 73 65 20 55 54 46  e16_v3() use UTF
2db40 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
2db50 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
2db60 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
2db70 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
2db80 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
2db90 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2dba0 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
2dbb0 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
2dbc0 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
2dbd0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
2dbe0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
2dbf0 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
2dc00 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
2dc10 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2dc20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
2dc30 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
2dc40 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
2dc50 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
2dc60 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
2dc70 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
2dc80 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
2dc90 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
2dca0 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
2dcb0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
2dcc0 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
2dcd0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2dce0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
2dcf0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
2dd00 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
2dd10 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
2dd20 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
2dd30 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
2dd40 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
2dd50 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
2dd60 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
2dd70 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
2dd80 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
2dd90 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
2dda0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
2ddb0 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
2ddc0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
2ddd0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
2dde0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
2ddf0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
2de00 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
2de10 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
2de20 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
2de30 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
2de40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2de50 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
2de60 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
2de70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
2de80 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
2de90 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
2dea0 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
2deb0 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
2dec0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
2ded0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
2dee0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
2def0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
2df00 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
2df10 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
2df20 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
2df30 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
2df40 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
2df50 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
2df60 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
2df70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
2df80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2df90 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
2dfa0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
2dfb0 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
2dfc0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
2dfd0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
2dfe0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
2dff0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
2e000 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
2e010 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2e020 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
2e030 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2e040 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2e050 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
2e060 72 65 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c  repare_v2(), sql
2e070 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2e080 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2e090 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e  re16_v2(),.** an
2e0a0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2e0b0 65 31 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61  e16_v3() interfa
2e0c0 63 65 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e  ces are recommen
2e0d0 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
2e0e0 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65  programs..** The
2e0f0 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
2e100 73 20 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s (sqlite3_prepa
2e110 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
2e120 5f 70 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a  _prepare16()).**
2e130 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
2e140 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
2e150 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
2e160 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
2e170 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
2e180 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61  the "vX" interfa
2e190 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
2e1a0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
2e1b0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
2e1c0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2e1d0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
2e1e0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
2e1f0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
2e200 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
2e210 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
2e220 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
2e230 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
2e240 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
2e250 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
2e260 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
2e270 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2e280 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
2e290 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
2e2a0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2e2b0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
2e2c0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
2e2d0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
2e2e0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
2e2f0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2e300 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
2e310 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
2e320 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
2e330 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
2e340 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
2e350 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
2e360 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
2e370 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2e380 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
2e390 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
2e3a0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2e3b0 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
2e3c0 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
2e3d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2e3e0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
2e3f0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
2e400 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
2e410 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
2e420 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
2e430 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
2e440 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
2e450 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
2e460 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
2e470 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
2e480 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
2e490 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
2e4a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
2e4b0 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
2e4c0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
2e4d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e4e0 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
2e4f0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
2e500 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
2e510 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
2e520 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
2e530 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
2e540 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
2e550 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
2e560 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
2e570 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
2e580 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
2e590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
2e5a0 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
2e5b0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
2e5c0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
2e5d0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
2e5e0 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
2e5f0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
2e600 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2e610 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
2e620 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
2e630 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2e640 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2e650 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
2e660 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
2e670 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
2e680 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
2e690 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
2e6a0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
2e6b0 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
2e6c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2e6d0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
2e6e0 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
2e6f0 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
2e700 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
2e710 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
2e720 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
2e730 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2e740 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
2e750 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
2e760 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2e770 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
2e780 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
2e790 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
2e7a0 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
2e7b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
2e7c0 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
2e7d0 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
2e7e0 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
2e7f0 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
2e800 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2e810 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c  is enabled..** <
2e820 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  /li>.** </ol>.**
2e830 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f  .** <p>^sqlite3_
2e840 70 72 65 70 61 72 65 5f 76 33 28 29 20 64 69 66  prepare_v3() dif
2e850 66 65 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  fers from sqlite
2e860 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f  3_prepare_v2() o
2e870 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a  nly in having.**
2e880 20 74 68 65 20 65 78 74 72 61 20 70 72 65 70 46   the extra prepF
2e890 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20  lags parameter, 
2e8a0 77 68 69 63 68 20 69 73 20 61 20 62 69 74 20 61  which is a bit a
2e8b0 72 72 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20  rray consisting 
2e8c0 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f  of zero or.** mo
2e8d0 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
2e8e0 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2e8f0 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50  TENT|SQLITE_PREP
2e900 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e  ARE_*] flags.  ^
2e910 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
2e920 72 65 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65  repare_v2() inte
2e930 72 66 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63  rface works exac
2e940 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a  tly the same as.
2e950 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
2e960 72 65 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a  re_v3() with a z
2e970 65 72 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61  ero prepFlags pa
2e980 72 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20  rameter..*/.int 
2e990 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2e9a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2e9b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2e9c0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2e9d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2e9e0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2e9f0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2ea00 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2ea10 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2ea20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2ea30 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2ea40 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2ea50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2ea60 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2ea70 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2ea80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2ea90 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2eaa0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2eab0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2eac0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2ead0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2eae0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2eaf0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2eb00 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2eb10 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2eb20 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2eb30 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2eb40 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2eb50 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2eb60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2eb70 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2eb80 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2eb90 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2eba0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2ebb0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2ebc0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ebd0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2ebe0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2ebf0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2ec00 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2ec10 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2ec20 5f 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73  _prepare_v3(.  s
2ec30 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2ec40 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2ec50 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2ec60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2ec70 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2ec80 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2ec90 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2eca0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2ecb0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2ecc0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2ecd0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73   bytes. */.  uns
2ece0 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c  igned int prepFl
2ecf0 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20  ags, /* Zero or 
2ed00 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50  more SQLITE_PREP
2ed10 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20  ARE_ flags */.  
2ed20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2ed30 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2ed40 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2ed50 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2ed60 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2ed70 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2ed80 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2ed90 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2eda0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2edb0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
2edc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2edd0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2ede0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2edf0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2ee00 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2ee10 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2ee20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2ee30 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2ee40 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2ee50 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2ee60 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2ee70 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2ee80 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2ee90 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2eea0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2eeb0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2eec0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2eed0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2eee0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2eef0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
2ef00 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2ef10 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2ef20 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2ef30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2ef40 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2ef50 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2ef60 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2ef70 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2ef80 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2ef90 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2efa0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2efb0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2efc0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2efd0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2efe0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2eff0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2f000 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2f010 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2f020 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2f030 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2f040 31 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33  16_v3(.  sqlite3
2f050 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2f060 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2f070 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2f080 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2f090 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2f0a0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2f0b0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2f0c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2f0d0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2f0e0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2f0f0 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64  s. */.  unsigned
2f100 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20   int prepFlags, 
2f110 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  /* Zero or more 
2f120 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20  SQLITE_PREPARE_ 
2f130 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74  flags */.  sqlit
2f140 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2f150 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2f160 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2f170 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2f180 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2f190 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2f1a0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2f1b0 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
2f1c0 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
2f1d0 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
2f1e0 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  QL.** METHOD: sq
2f1f0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f200 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71   ^The sqlite3_sq
2f210 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  l(P) interface r
2f220 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2f230 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68   to a copy of th
2f240 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74  e UTF-8.** SQL t
2f250 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
2f260 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  te [prepared sta
2f270 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77  tement] P if P w
2f280 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  as.** created by
2f290 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f2a0 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2f2b0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
2f2c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2f2d0 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72  pare16_v2()], or
2f2e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f2f0 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54  e16_v3()]..** ^T
2f300 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  he sqlite3_expan
2f310 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  ded_sql(P) inter
2f320 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2f330 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d  ointer to a UTF-
2f340 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  8.** string cont
2f350 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74  aining the SQL t
2f360 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20  ext of prepared 
2f370 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68  statement P with
2f380 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d  .** [bound param
2f390 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e  eters] expanded.
2f3a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f3b0 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2f3c0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2f3d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2f3e0 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2f3f0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2f400 68 65 20 6e 6f 72 6d 61 6c 69 7a 65 64 20 53 51  he normalized SQ
2f410 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72  L text of prepar
2f420 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 2e 20  ed statement P. 
2f430 20 54 68 65 0a 2a 2a 20 73 65 6d 61 6e 74 69 63   The.** semantic
2f440 73 20 75 73 65 64 20 74 6f 20 6e 6f 72 6d 61 6c  s used to normal
2f450 69 7a 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d  ize a SQL statem
2f460 65 6e 74 20 61 72 65 20 75 6e 73 70 65 63 69 66  ent are unspecif
2f470 69 65 64 20 61 6e 64 20 73 75 62 6a 65 63 74 0a  ied and subject.
2f480 2a 2a 20 74 6f 20 63 68 61 6e 67 65 2e 20 20 41  ** to change.  A
2f490 74 20 61 20 6d 69 6e 69 6d 75 6d 2c 20 6c 69 74  t a minimum, lit
2f4a0 65 72 61 6c 20 76 61 6c 75 65 73 20 77 69 6c 6c  eral values will
2f4b0 20 62 65 20 72 65 70 6c 61 63 65 64 20 77 69 74   be replaced wit
2f4c0 68 20 73 75 69 74 61 62 6c 65 0a 2a 2a 20 70 6c  h suitable.** pl
2f4d0 61 63 65 68 6f 6c 64 65 72 73 2e 0a 2a 2a 0a 2a  aceholders..**.*
2f4e0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2f4f0 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20 73   if a prepared s
2f500 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61  tatement is crea
2f510 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ted using the SQ
2f520 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43  L.** text "SELEC
2f530 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64  T $abc,:xyz" and
2f540 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24 61   if parameter $a
2f550 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69  bc is bound to i
2f560 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61  nteger 2345.** a
2f570 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79  nd parameter :xy
2f580 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68  z is unbound, th
2f590 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  en sqlite3_sql()
2f5a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2f5b0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72  the original str
2f5c0 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62  ing, "SELECT $ab
2f5d0 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69  c,:xyz" but sqli
2f5e0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2f5f0 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  ().** will retur
2f600 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e  n "SELECT 2345,N
2f610 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ULL".)^.**.** ^T
2f620 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  he sqlite3_expan
2f630 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66  ded_sql() interf
2f640 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ace returns NULL
2f650 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
2f660 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76   memory.** is av
2f670 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20  ailable to hold 
2f680 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69  the result, or i
2f690 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75  f the result wou
2f6a0 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ld exceed the.**
2f6b0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72   the maximum str
2f6c0 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72  ing length deter
2f6d0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51  mined by the [SQ
2f6e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2f6f0 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  H]..**.** ^The [
2f700 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
2f710 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
2f720 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d  -time option lim
2f730 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a  its the size of.
2f740 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ** bound paramet
2f750 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20  er expansions.  
2f760 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  ^The [SQLITE_OMI
2f770 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  T_TRACE] compile
2f780 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
2f790 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65  causes sqlite3_e
2f7a0 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f  xpanded_sql() to
2f7b0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e   always return N
2f7c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2f7d0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
2f7e0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2f7f0 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6e  P) and sqlite3_n
2f800 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28 50 29  ormalized_sql(P)
2f810 0a 2a 2a 20 61 72 65 20 6d 61 6e 61 67 65 64 20  .** are managed 
2f820 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 61 72  by SQLite and ar
2f830 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2f840 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2f850 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2f860 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2f870 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2f880 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2f890 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2f8a0 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2f8b0 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2f8c0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2f8d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2f8e0 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2f8f0 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2f900 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2f910 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2f920 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f  3_free()]..*/.co
2f930 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2f940 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
2f950 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72  mt *pStmt);.char
2f960 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64   *sqlite3_expand
2f970 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  ed_sql(sqlite3_s
2f980 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 6f 6e  tmt *pStmt);.con
2f990 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2f9a0 5f 6e 6f 72 6d 61 6c 69 7a 65 64 5f 73 71 6c 28  _normalized_sql(
2f9b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2f9c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2f9d0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2f9e0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
2f9f0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
2fa00 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
2fa10 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2fa20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fa30 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2fa40 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
2fa50 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2fa60 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
2fa70 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
2fa80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fa90 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
2faa0 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
2fab0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
2fac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2fad0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
2fae0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
2faf0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2fb00 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
2fb10 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
2fb20 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
2fb30 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
2fb40 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
2fb50 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
2fb60 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
2fb70 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2fb80 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
2fb90 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
2fba0 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
2fbb0 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
2fbc0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
2fbd0 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
2fbe0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
2fbf0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
2fc00 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
2fc10 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2fc20 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
2fc30 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
2fc40 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
2fc50 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
2fc60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2fc70 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
2fc80 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2fc90 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2fca0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2fcb0 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
2fcc0 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
2fcd0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
2fce0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
2fcf0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
2fd00 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
2fd10 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
2fd20 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
2fd30 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
2fd40 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
2fd50 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
2fd60 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
2fd70 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2fd80 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2fd90 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
2fda0 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
2fdb0 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
2fdc0 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
2fdd0 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
2fde0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
2fdf0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
2fe00 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
2fe10 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
2fe20 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
2fe30 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
2fe40 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
2fe50 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
2fe60 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
2fe70 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2fe80 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
2fe90 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
2fea0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
2feb0 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
2fec0 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
2fed0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
2fee0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
2fef0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
2ff00 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2ff10 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2ff20 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e  es on disk..** ^
2ff30 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2ff40 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65  _readonly() inte
2ff50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2ff60 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73  ue for [BEGIN] s
2ff70 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20  ince.** [BEGIN] 
2ff80 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65  merely sets inte
2ff90 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20  rnal flags, but 
2ffa0 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  the [BEGIN|BEGIN
2ffb0 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a   IMMEDIATE] and.
2ffc0 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  ** [BEGIN|BEGIN 
2ffd0 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61  EXCLUSIVE] comma
2ffe0 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65  nds do touch the
2fff0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f   database and so
30000 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
30010 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75  _readonly() retu
30020 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68  rns false for th
30030 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f  ose commands..*/
30040 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
30050 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
30060 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
30070 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30080 3a 20 51 75 65 72 79 20 54 68 65 20 45 58 50 4c  : Query The EXPL
30090 41 49 4e 20 53 65 74 74 69 6e 67 20 46 6f 72 20  AIN Setting For 
300a0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
300b0 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
300c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
300d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
300e0 73 74 6d 74 5f 69 73 65 78 70 6c 61 69 6e 28 53  stmt_isexplain(S
300f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
30100 72 6e 73 20 31 20 69 66 20 74 68 65 0a 2a 2a 20  rns 1 if the.** 
30110 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30120 6e 74 20 53 20 69 73 20 61 6e 20 45 58 50 4c 41  nt S is an EXPLA
30130 49 4e 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72  IN statement, or
30140 20 32 20 69 66 20 74 68 65 0a 2a 2a 20 73 74 61   2 if the.** sta
30150 74 65 6d 65 6e 74 20 53 20 69 73 20 61 6e 20 45  tement S is an E
30160 58 50 4c 41 49 4e 20 51 55 45 52 59 20 50 4c 41  XPLAIN QUERY PLA
30170 4e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  N..** ^The sqlit
30180 65 33 5f 73 74 6d 74 5f 69 73 65 78 70 6c 61 69  e3_stmt_isexplai
30190 6e 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  n(S) interface r
301a0 65 74 75 72 6e 73 20 30 20 69 66 20 53 20 69 73  eturns 0 if S is
301b0 0a 2a 2a 20 61 6e 20 6f 72 64 69 6e 61 72 79 20  .** an ordinary 
301c0 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 20 4e  statement or a N
301d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
301e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
301f0 5f 69 73 65 78 70 6c 61 69 6e 28 73 71 6c 69 74  _isexplain(sqlit
30200 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
30210 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30220 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
30230 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
30240 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
30250 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
30260 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30270 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
30280 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
30290 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
302a0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
302b0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
302c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
302d0 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
302e0 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
302f0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
30300 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
30310 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20   neither run to 
30320 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75  completion (retu
30330 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
30340 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69  DONE] from [sqli
30350 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f  te3_step(S)]) no
30360 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20  r.** been reset 
30370 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
30380 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
30390 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
303a0 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
303b0 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
303c0 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
303d0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
303e0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
303f0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
30400 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
30410 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
30420 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
30430 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
30440 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
30450 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
30460 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
30470 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
30480 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
30490 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
304a0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
304b0 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
304c0 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
304d0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
304e0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
304f0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
30500 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
30510 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
30520 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
30530 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
30540 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
30550 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
30560 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
30570 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
30580 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
30590 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
305a0 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
305b0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
305c0 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
305d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
305e0 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
305f0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
30600 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
30610 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
30620 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
30630 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30640 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
30650 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
30660 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
30670 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
30680 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
30690 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
306a0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
306b0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
306c0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
306d0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
306e0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
306f0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
30700 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
30710 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
30720 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
30730 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
30740 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
30750 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
30760 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
30770 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
30780 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
30790 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
307a0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
307b0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
307c0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
307d0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
307e0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
307f0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
30800 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
30810 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
30820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
30830 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
30840 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
30850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
30860 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
30870 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
30880 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
30890 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
308a0 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
308b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
308c0 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
308d0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
308e0 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
308f0 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
30900 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
30910 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
30920 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
30930 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
30940 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
30950 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
30960 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
30970 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
30980 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
30990 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
309a0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
309b0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
309c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
309d0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
309e0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
309f0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
30a00 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
30a10 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
30a20 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
30a30 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
30a40 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
30a50 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
30a60 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
30a70 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
30a80 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
30a90 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
30aa0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
30ab0 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
30ac0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
30ad0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
30ae0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
30af0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
30b00 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
30b10 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
30b20 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
30b30 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
30b40 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
30b50 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
30b60 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
30b70 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
30b80 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
30b90 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
30ba0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
30bb0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
30bc0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
30bd0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
30be0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
30bf0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
30c00 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
30c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
30c20 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
30c30 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
30c40 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
30c50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
30c60 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
30c70 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
30c80 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
30c90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30ca0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
30cb0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
30cc0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
30cd0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
30ce0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
30cf0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
30d00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
30d10 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
30d20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
30d30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30d40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
30d50 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
30d60 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a   as arguments.**
30d70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
30d80 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b 73  ult_value()], [s
30d90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
30da0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
30db0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
30dc0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
30dd0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
30de0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
30df0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
30e00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
30e10 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
30e20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
30e30 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
30e40 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
30e50 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f  3_value sqlite3_
30e60 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
30e70 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
30e80 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
30e90 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
30ea0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
30eb0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
30ec0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
30ed0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
30ee0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
30ef0 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
30f00 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
30f10 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
30f20 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
30f30 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
30f40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30f50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
30f60 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
30f70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
30f80 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
30f90 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
30fa0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
30fb0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
30fc0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
30fd0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
30fe0 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
30ff0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
31000 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
31010 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
31020 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
31030 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
31040 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
31050 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
31060 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
31070 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
31080 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
31090 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
310a0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
310b0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
310c0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
310d0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
310e0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
310f0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
31100 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
31110 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
31120 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
31130 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
31140 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
31150 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
31160 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
31170 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
31180 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
31190 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
311a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
311b0 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
311c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
311d0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
311e0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
311f0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
31200 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
31210 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
31220 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
31230 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
31240 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
31250 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
31260 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
31270 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
31280 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
31290 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
312a0 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
312b0 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
312c0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
312d0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
312e0 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
312f0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
31300 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
31310 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
31320 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
31330 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
31340 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
31350 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
31360 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
31370 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
31380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
31390 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
313a0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
313b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
313c0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
313d0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
313e0 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
313f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
31400 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
31410 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
31420 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
31430 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
31440 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
31450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
31460 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
31470 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
31480 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
31490 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
314a0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
314b0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
314c0 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
314d0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
314e0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
314f0 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
31500 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
31510 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
31520 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
31530 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
31540 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
31550 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
31560 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
31570 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
31580 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
31590 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
315a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
315b0 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
315c0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
315d0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
315e0 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
315f0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
31600 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
31610 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
31620 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
31630 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
31640 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
31650 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
31660 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
31670 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
31680 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
31690 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
316a0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
316b0 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
316c0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
316d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
316e0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
316f0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
31700 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
31710 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
31720 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
31730 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
31740 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
31750 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
31760 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
31770 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
31780 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
31790 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
317a0 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
317b0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
317c0 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
317d0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
317e0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
317f0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
31800 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
31810 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
31820 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
31830 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
31840 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
31850 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
31860 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
31870 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
31880 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
31890 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
318a0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
318b0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
318c0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
318d0 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
318e0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
318f0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
31900 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
31910 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
31920 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
31930 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
31940 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
31950 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
31960 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
31970 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
31980 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
31990 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
319a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
319b0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
319c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
319d0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
319e0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
319f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
31a00 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
31a10 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
31a20 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
31a30 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
31a40 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
31a50 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
31a60 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
31a70 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
31a80 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
31a90 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
31aa0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
31ab0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
31ac0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
31ad0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
31ae0 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
31af0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
31b00 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
31b10 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
31b20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
31b30 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
31b40 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
31b50 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
31b60 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
31b70 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
31b80 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
31b90 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
31ba0 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
31bb0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
31bc0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
31bd0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
31be0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
31bf0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
31c00 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
31c10 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
31c20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
31c30 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
31c40 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
31c50 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
31c60 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
31c70 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2c   bind API fails,
31c80 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 65 20 64  .** except the d
31c90 65 73 74 72 75 63 74 6f 72 20 69 73 20 6e 6f 74  estructor is not
31ca0 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 74   called if the t
31cb0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
31cc0 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  s a NULL.** poin
31cd0 74 65 72 20 6f 72 20 74 68 65 20 66 6f 75 72 74  ter or the fourt
31ce0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
31cf0 65 67 61 74 69 76 65 2e 0a 2a 2a 20 5e 49 66 20  egative..** ^If 
31d00 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
31d10 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
31d20 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
31d30 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
31d40 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
31d50 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
31d60 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
31d70 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
31d80 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
31d90 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
31da0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
31db0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
31dc0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
31dd0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
31de0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
31df0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
31e00 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
31e10 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
31e20 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
31e30 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
31e40 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
31e50 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
31e60 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
31e70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
31e80 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
31e90 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
31ea0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
31eb0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
31ec0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
31ed0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
31ee0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
31ef0 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
31f00 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
31f10 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
31f20 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
31f30 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
31f40 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
31f50 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
31f60 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
31f70 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
31f80 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
31f90 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
31fa0 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
31fb0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
31fc0 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
31fd0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
31fe0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
31ff0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
32000 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32010 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
32020 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
32030 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
32040 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
32050 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
32060 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
32070 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
32080 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
32090 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
320a0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
320b0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
320c0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
320d0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
320e0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
320f0 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
32100 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
32110 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
32120 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
32130 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
32140 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
32150 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
32160 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
32170 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
32180 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
32190 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
321a0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
321b0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  B..**.** ^The sq
321c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74  lite3_bind_point
321d0 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f  er(S,I,P,T,D) ro
321e0 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68 65  utine causes the
321f0 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   I-th parameter 
32200 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  in.** [prepared 
32210 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20  statement] S to 
32220 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75  have an SQL valu
32230 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74  e of NULL, but t
32240 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73  o also be.** ass
32250 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
32260 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79   pointer P of ty
32270 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69 74  pe T.  ^D is eit
32280 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
32290 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74  er or.** a point
322a0 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74  er to a destruct
322b0 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20  or function for 
322c0 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  P. ^SQLite will 
322d0 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65  invoke the.** de
322e0 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
322f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
32300 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20 69  t of P when it i
32310 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
32320 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70 61  .** P.  The T pa
32330 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
32340 65 20 61 20 73 74 61 74 69 63 20 73 74 72 69 6e  e a static strin
32350 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61 20  g, preferably a 
32360 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61  string.** litera
32370 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  l. The sqlite3_b
32380 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f  ind_pointer() ro
32390 75 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f 66  utine is part of
323a0 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72   the.** [pointer
323b0 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66 61   passing interfa
323c0 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53 51  ce] added for SQ
323d0 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a  Lite 3.20.0..**.
323e0 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
323f0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
32400 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
32410 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
32420 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
32430 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
32440 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
32450 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
32460 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
32470 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
32480 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
32490 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
324a0 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
324b0 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
324c0 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
324d0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
324e0 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
324f0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
32500 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
32510 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
32520 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
32530 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
32540 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
32550 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
32560 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
32570 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
32580 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
32590 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
325a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
325b0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
325c0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
325d0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
325e0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
325f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
32600 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
32610 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
32620 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
32630 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
32640 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
32650 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
32660 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
32670 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
32680 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
32690 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
326a0 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
326b0 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
326c0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
326d0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
326e0 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
326f0 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
32700 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
32710 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
32720 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
32730 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
32740 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
32750 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
32760 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
32770 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
32780 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
32790 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
327a0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
327b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
327c0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
327d0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
327e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
327f0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
32800 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
32810 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
32820 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32830 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
32840 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
32850 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
32860 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32870 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
32880 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
32890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
328a0 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
328b0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
328c0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
328d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
328e0 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
328f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
32900 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
32910 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
32920 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
32930 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
32940 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
32950 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
32960 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
32970 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
32980 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
32990 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
329a0 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  stmt*,int,const 
329b0 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a  char*,int,void(*
329c0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
329d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
329e0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
329f0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
32a00 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
32a10 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
32a20 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
32a30 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
32a40 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
32a50 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
32a60 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
32a70 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
32a80 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
32a90 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
32aa0 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ng);.int sqlite3
32ab0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
32ac0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
32ad0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
32ae0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
32af0 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
32b00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
32b10 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  nt, void*, const
32b20 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76   char*,void(*)(v
32b30 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
32b40 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
32b50 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
32b60 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e   int, int n);.in
32b70 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
32b80 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
32b90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
32ba0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a  lite3_uint64);..
32bb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32bc0 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
32bd0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48  rameters.** METH
32be0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
32bf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
32c00 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
32c10 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
32c20 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
32c30 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
32c40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32c50 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
32c60 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
32c70 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
32c80 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
32c90 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
32ca0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
32cb0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
32cc0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
32cd0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
32ce0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
32cf0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
32d00 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
32d10 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
32d20 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
32d30 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
32d40 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
32d50 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
32d60 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
32d70 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
32d80 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
32d90 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
32da0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
32db0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
32dc0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
32dd0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
32de0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
32df0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
32e00 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
32e10 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
32e20 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
32e30 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
32e40 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
32e50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
32e60 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
32e70 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
32e80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
32e90 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
32ea0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
32eb0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
32ec0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
32ed0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
32ee0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
32ef0 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f  rameter.** METHO
32f00 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
32f10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32f20 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
32f30 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
32f40 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
32f50 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
32f60 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
32f70 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
32f80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32f90 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
32fa0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
32fb0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
32fc0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
32fd0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
32fe0 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
32ff0 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
33000 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
33010 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
33020 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
33030 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
33040 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
33050 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
33060 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
33070 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
33080 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
33090 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
330a0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
330b0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
330c0 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
330d0 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
330e0 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
330f0 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
33100 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
33110 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
33120 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
33130 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
33140 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
33150 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
33160 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
33170 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
33180 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
33190 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
331a0 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
331b0 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
331c0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
331d0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
331e0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
331f0 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
33200 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
33210 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
33220 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
33230 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
33240 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71  are16()],.** [sq
33250 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
33260 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  v2()], or [sqlit
33270 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
33280 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
33290 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
332a0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
332b0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
332c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
332d0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
332e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
332f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
33300 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
33310 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
33320 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
33330 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33340 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
33350 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
33360 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
33370 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
33380 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33390 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
333a0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
333b0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
333c0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
333d0 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
333e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
333f0 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
33400 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
33410 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
33420 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
33430 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
33440 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
33450 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
33460 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
33470 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
33480 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
33490 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
334a0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
334b0 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
334c0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
334d0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
334e0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
334f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
33500 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
33510 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
33520 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
33530 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
33540 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
33550 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
33560 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
33570 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
33580 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
33590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
335a0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a  ameter_name()]..
335b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
335c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
335d0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
335e0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
335f0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
33600 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
33610 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
33620 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
33630 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
33640 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
33650 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
33660 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
33670 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
33680 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
33690 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
336a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
336b0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
336c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
336d0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
336e0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
336f0 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
33700 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
33710 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33720 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
33730 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
33740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33750 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
33760 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
33770 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
33780 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
33790 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
337a0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
337b0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
337c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
337d0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
337e0 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68  atement]. ^If th
337f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
33800 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73  ns 0, that means
33810 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72   the .** [prepar
33820 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65  ed statement] re
33830 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66  turns no data (f
33840 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
33850 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77  PDATE])..** ^How
33860 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75  ever, just becau
33870 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
33880 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69  returns a positi
33890 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e  ve number does n
338a0 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  ot.** mean that 
338b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73  one or more rows
338c0 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65   of data will be
338d0 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53   returned.  ^A S
338e0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a  ELECT statement.
338f0 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68  ** will always h
33900 61 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73  ave a positive s
33910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
33920 75 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64  unt() but depend
33930 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48  ing on the.** WH
33940 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
33950 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74  raints and the t
33960 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74  able content, it
33970 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f   might return no
33980 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   rows..**.** See
33990 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
339a0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
339b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
339c0 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
339d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
339e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
339f0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
33a00 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
33a10 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
33a20 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
33a30 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
33a40 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
33a50 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
33a60 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
33a70 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
33a80 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
33a90 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
33aa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
33ab0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
33ac0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
33ad0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
33ae0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
33af0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
33b00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
33b10 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
33b20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
33b30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
33b40 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
33b50 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
33b60 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
33b70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33b80 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
33b90 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
33ba0 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
33bb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
33bc0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
33bd0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
33be0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
33bf0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
33c00 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
33c10 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
33c20 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
33c30 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
33c40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
33c50 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
33c60 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
33c70 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
33c80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
33c90 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
33ca0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
33cb0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
33cc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
33cd0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
33ce0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
33cf0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
33d00 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
33d10 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
33d20 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
33d30 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
33d40 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
33d50 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
33d60 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
33d70 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
33d80 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
33d90 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
33da0 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
33db0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
33dc0 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
33dd0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
33de0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
33df0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
33e00 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
33e10 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
33e20 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
33e30 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
33e40 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
33e50 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
33e60 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
33e70 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
33e80 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
33e90 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
33ea0 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
33eb0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
33ec0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
33ed0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
33ee0 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
33ef0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
33f00 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
33f10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
33f20 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
33f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
33f40 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
33f50 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
33f60 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
33f70 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
33f80 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
33f90 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
33fa0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
33fb0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
33fc0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
33fd0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
33fe0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
33ff0 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
34000 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
34010 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
34020 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
34030 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
34040 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
34050 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
34060 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
34070 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
34080 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
34090 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
340a0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
340b0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
340c0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
340d0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
340e0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
340f0 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
34100 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
34110 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
34120 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
34130 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
34140 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
34150 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
34160 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
34170 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
34180 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
34190 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
341a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
341b0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
341c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
341d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
341e0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
341f0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
34200 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34210 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
34220 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
34230 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
34240 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
34250 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
34260 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
34270 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
34280 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
34290 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
342a0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
342b0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
342c0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
342d0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
342e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
342f0 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
34300 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
34310 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34320 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
34330 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
34340 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
34350 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
34360 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
34370 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
34380 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
34390 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
343a0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
343b0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
343c0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
343d0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
343e0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
343f0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
34400 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
34410 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
34420 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
34430 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
34440 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
34450 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
34460 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
34470 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
34480 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
34490 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
344a0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
344b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
344c0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
344d0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
344e0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
344f0 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
34500 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
34510 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
34520 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
34530 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
34540 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
34550 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
34560 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
34570 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
34580 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
34590 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
345a0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
345b0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
345c0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
345d0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
345e0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
345f0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
34600 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
34610 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
34620 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
34630 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
34640 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
34650 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
34660 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
34670 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
34680 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
34690 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
346a0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
346b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
346c0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
346d0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
346e0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
346f0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
34700 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
34710 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
34720 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
34730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
34740 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
34750 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
34760 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
34770 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
34780 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34790 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
347a0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
347b0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
347c0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
347d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
347e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
347f0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
34800 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
34810 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
34820 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
34830 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
34840 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
34850 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
34860 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
34870 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
34880 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
34890 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
348a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
348b0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
348c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
348d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
348e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
348f0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
34900 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
34910 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
34920 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
34930 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
34940 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
34950 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
34960 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
34970 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
34980 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
34990 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  tmt.**.** ^(The 
349a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
349b0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
349c0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
349d0 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
349e0 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
349f0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
34a00 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
34a10 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
34a20 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
34a30 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
34a40 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
34a50 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
34a60 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
34a70 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
34a80 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
34a90 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
34aa0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
34ab0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
34ac0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
34ad0 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
34ae0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
34af0 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
34b00 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
34b10 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
34b20 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
34b30 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
34b40 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
34b50 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
34b60 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
34b70 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
34b80 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
34b90 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
34ba0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
34bb0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
34bc0 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
34bd0 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
34be0 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
34bf0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
34c00 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
34c10 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
34c20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
34c30 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
34c40 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
34c50 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
34c60 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
34c70 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
34c80 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
34c90 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
34ca0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
34cb0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
34cc0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
34cd0 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
34ce0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
34cf0 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
34d00 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
34d10 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
34d20 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
34d30 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
34d40 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
34d50 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
34d60 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
34d70 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
34d80 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
34d90 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
34da0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
34db0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
34dc0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
34dd0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
34de0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
34df0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
34e00 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
34e10 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
34e20 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
34e30 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
34e40 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
34e50 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
34e60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34e70 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
34e80 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  L Statement.** M
34e90 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
34ea0 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  tmt.**.** After 
34eb0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
34ec0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
34ed0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 61  prepared using a
34ee0 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ny of.** [sqlite
34ef0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
34f00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34f10 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v3()], [sqlite
34f20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
34f30 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
34f40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
34f50 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
34f60 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
34f70 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
34f80 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
34f90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
34fa0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
34fb0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
34fc0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
34fd0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
34fe0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
34ff0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
35000 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
35010 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
35020 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
35030 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
35040 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
35050 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
35060 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
35070 72 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  r "vX" interface
35080 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
35090 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
350a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
350b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
350c0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a 2a  epare16_v3()],.*
350d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
350e0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
350f0 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
35100 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
35110 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
35120 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
35130 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
35140 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
35150 65 77 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  ew "vX" interfac
35160 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
35170 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
35180 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
35190 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
351a0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
351b0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
351c0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
351d0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
351e0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
351f0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
35200 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
35210 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
35220 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
35230 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
35240 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
35250 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
35260 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
35270 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
35280 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
35290 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
352a0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
352b0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
352c0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
352d0 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
352e0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
352f0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
35300 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
35310 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
35320 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
35330 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
35340 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
35350 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
35360 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
35370 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
35380 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
35390 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
353a0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
353b0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
353c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
353d0 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
353e0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
353f0 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
35400 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
35410 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
35420 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
35430 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
35440 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
35450 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
35460 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
35470 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
35480 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
35490 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
354a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
354b0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
354c0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
354d0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
354e0 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
354f0 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
35500 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
35510 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
35520 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
35530 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
35540 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
35550 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
35560 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
35570 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
35580 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
35590 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
355a0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
355b0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
355c0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
355d0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
355e0 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
355f0 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
35600 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
35610 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
35620 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
35630 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
35640 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
35650 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
35660 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
35670 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
35680 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
35690 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
356a0 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
356b0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
356c0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
356d0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
356e0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
356f0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
35700 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
35710 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
35720 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
35730 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
35740 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
35750 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
35760 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
35770 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
35780 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
35790 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
357a0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
357b0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
357c0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
357d0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
357e0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
357f0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
35800 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
35810 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
35820 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
35830 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
35840 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
35850 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
35860 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
35870 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
35880 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
35890 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
358a0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
358b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
358c0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
358d0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
358e0 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
358f0 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
35900 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
35910 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
35920 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
35930 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
35940 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
35950 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
35960 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
35970 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
35980 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
35990 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
359a0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
359b0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
359c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
359d0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
359e0 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
359f0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
35a00 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
35a10 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
35a20 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
35a30 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
35a40 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
35a50 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
35a60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
35a70 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
35a80 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
35a90 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
35aa0 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
35ab0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
35ac0 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
35ad0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
35ae0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
35af0 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
35b00 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
35b10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
35b20 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
35b30 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
35b40 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
35b50 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
35b60 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
35b70 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
35b80 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20   after [version 
35b90 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65  3.6.23.1] ([date
35ba0 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a  of:3.6.23.1],.**
35bb0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
35bc0 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
35bd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
35be0 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
35bf0 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
35c00 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
35c10 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
35c20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
35c30 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
35c40 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
35c50 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
35c60 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
35c70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
35c80 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
35c90 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
35ca0 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
35cb0 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
35cc0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
35cd0 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
35ce0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
35cf0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
35d00 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
35d10 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
35d20 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
35d30 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
35d40 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
35d50 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
35d60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
35d70 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
35d80 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
35d90 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
35da0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
35db0 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
35dc0 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
35dd0 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
35de0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
35df0 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
35e00 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
35e10 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
35e20 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
35e30 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
35e40 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
35e50 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
35e60 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
35e70 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
35e80 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
35e90 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
35ea0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
35eb0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
35ec0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
35ed0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
35ee0 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
35ef0 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
35f00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
35f10 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
35f20 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f  _prepare_v3()] o
35f30 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
35f40 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b  re_v2()].** or [
35f50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
35f60 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  6_v2()] or [sqli
35f70 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
35f80 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
35f90 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
35fa0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
35fb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
35fc0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
35fd0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
35fe0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
35ff0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
36000 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
36010 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
36020 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
36030 75 73 65 20 6f 66 20 74 68 65 20 22 76 58 22 20  use of the "vX" 
36040 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 72 65  interfaces is re
36050 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
36060 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
36070 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
36080 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36090 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
360a0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
360b0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
360c0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
360d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
360e0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
360f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
36100 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
36110 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
36120 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
36130 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
36140 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36150 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
36160 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
36170 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
36180 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
36190 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
361a0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
361b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
361c0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
361d0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
361e0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
361f0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
36200 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
36210 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
36220 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
36230 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
36240 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
36250 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
36260 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
36270 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
36280 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
36290 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
362a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
362b0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
362c0 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
362d0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
362e0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
362f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
36300 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
36310 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36320 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
36330 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
36340 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
36350 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
36360 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
36370 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
36380 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
36390 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
363a0 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
363b0 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
363c0 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
363d0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
363e0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
363f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
36400 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
36410 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
36420 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
36430 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
36440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
36450 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
36460 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
36470 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
36480 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
36490 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
364a0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
364b0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
364c0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
364d0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
364e0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
364f0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
36500 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
36510 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
36520 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
36530 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
36540 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
36550 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
36560 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
36570 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
36580 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
36590 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
365a0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
365b0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
365c0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
365d0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
365e0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
365f0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
36600 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
36610 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
36620 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
36630 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
36640 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
36650 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
36660 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
36670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
36680 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
36690 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
366a0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
366b0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
366c0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
366d0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
366e0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
366f0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
36700 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
36710 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
36720 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
36730 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
36740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36750 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
36760 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
36770 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
36780 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
36790 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
367a0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
367b0 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e   <b>Summary:</b>
367c0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
367d0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20  <table border=0 
367e0 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65  cellpadding=0 ce
367f0 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20  llspacing=0>.** 
36800 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
36810 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f  e3_column_blob</
36820 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
36830 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  BLOB result.** <
36840 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
36850 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c  3_column_double<
36860 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
36870 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20  >REAL result.** 
36880 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
36890 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62  e3_column_int</b
368a0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33  ><td>&rarr;<td>3
368b0 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65  2-bit INTEGER re
368c0 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
368d0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
368e0 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26  n_int64</b><td>&
368f0 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20  rarr;<td>64-bit 
36900 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a  INTEGER result.*
36910 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
36920 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36930 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
36940 64 3e 55 54 46 2d 38 20 54 45 58 54 20 72 65 73  d>UTF-8 TEXT res
36950 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
36960 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
36970 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26  _text16</b><td>&
36980 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20  rarr;<td>UTF-16 
36990 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  TEXT result.** <
369a0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
369b0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f  3_column_value</
369c0 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
369d0 54 68 65 20 72 65 73 75 6c 74 20 61 73 20 61 6e  The result as an
369e0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
369f0 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74 65 64 20  lue|unprotected 
36a00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36a10 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  bject..** <tr><t
36a20 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73  d>&nbsp;<td>&nbs
36a30 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20  p;<td>&nbsp;.** 
36a40 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
36a50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c  e3_column_bytes<
36a60 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
36a70 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a  >Size of a BLOB.
36a80 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38 20 54 45  ** or a UTF-8 TE
36a90 58 54 20 72 65 73 75 6c 74 20 69 6e 20 62 79 74  XT result in byt
36aa0 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  es.** <tr><td><b
36ab0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
36ac0 62 79 74 65 73 31 36 26 6e 62 73 70 3b 26 6e 62  bytes16&nbsp;&nb
36ad0 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26  sp;</b>.** <td>&
36ae0 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70  rarr;&nbsp;&nbsp
36af0 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55 54 46  ;<td>Size of UTF
36b00 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62  -16.** TEXT in b
36b10 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ytes.** <tr><td>
36b20 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
36b30 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72  n_type</b><td>&r
36b40 61 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a  arr;<td>Default.
36b50 2a 2a 20 64 61 74 61 74 79 70 65 20 6f 66 20 74  ** datatype of t
36b60 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74  he result.** </t
36b70 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  able></blockquot
36b80 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61  e>.**.** <b>Deta
36b90 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e  ils:</b>.**.** ^
36ba0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
36bb0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
36bc0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
36bd0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
36be0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
36bf0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
36c00 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
36c10 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
36c20 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
36c30 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
36c40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36c50 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
36c60 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
36c70 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
36c80 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
36c90 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
36ca0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
36cb0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
36cc0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
36cd0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
36ce0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
36cf0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
36d00 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
36d10 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
36d20 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
36d30 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
36d40 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
36d50 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
36d60 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
36d70 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
36d80 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
36d90 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
36da0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
36db0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
36dc0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
36dd0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
36de0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
36df0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
36e00 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
36e10 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
36e20 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
36e30 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
36e40 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
36e50 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
36e60 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
36e70 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
36e80 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
36e90 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
36ea0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
36eb0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
36ec0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
36ed0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
36ee0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
36ef0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
36f00 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
36f10 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
36f20 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
36f30 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
36f40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
36f50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
36f60 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
36f70 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
36f80 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
36f90 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
36fa0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
36fb0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
36fc0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
36fd0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
36fe0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
36ff0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
37000 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
37010 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
37020 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
37030 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
37040 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
37050 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
37060 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
37070 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
37080 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
37090 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72   first six inter
370a0 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64  faces (_blob, _d
370b0 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e  ouble, _int, _in
370c0 74 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20  t64, _text, and 
370d0 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65 61 63 68  _text16).** each
370e0 20 72 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75   return the valu
370f0 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
37100 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65 63 69 66  lumn in a specif
37110 69 63 20 64 61 74 61 20 66 6f 72 6d 61 74 2e 20  ic data format. 
37120 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c   If.** the resul
37130 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20  t column is not 
37140 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74 68 65  initially in the
37150 20 72 65 71 75 65 73 74 65 64 20 66 6f 72 6d 61   requested forma
37160 74 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  t (for example,.
37170 2a 2a 20 69 66 20 74 68 65 20 71 75 65 72 79 20  ** if the query 
37180 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
37190 65 72 20 62 75 74 20 74 68 65 20 73 71 6c 69 74  er but the sqlit
371a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
371b0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
371c0 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74   used to extract
371d0 20 74 68 65 20 76 61 6c 75 65 29 20 74 68 65 6e   the value) then
371e0 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 74 79   an automatic ty
371f0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  pe conversion is
37200 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a   performed..**.*
37210 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
37220 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
37230 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
37240 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
37250 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
37260 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
37270 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
37280 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
37290 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
372a0 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
372b0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
372c0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
372d0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
372e0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
372f0 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
37300 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54  LITE_NULL]..** T
37310 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
37320 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
37330 6e 5f 74 79 70 65 28 29 20 63 61 6e 20 62 65 20  n_type() can be 
37340 75 73 65 64 20 74 6f 20 64 65 63 69 64 65 20 77  used to decide w
37350 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66  hich.** of the f
37360 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61  irst six interfa
37370 63 65 20 73 68 6f 75 6c 64 20 62 65 20 75 73 65  ce should be use
37380 64 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65  d to extract the
37390 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a   column value..*
373a0 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
373b0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
373c0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
373d0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
373e0 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61   if no.** automa
373f0 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73  tic type convers
37400 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
37410 65 64 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ed for the value
37420 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a   in question.  .
37430 2a 2a 20 41 66 74 65 72 20 61 20 74 79 70 65 20  ** After a type 
37440 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65 20  conversion, the 
37450 72 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e  result of callin
37460 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  g sqlite3_column
37470 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e  _type().** is un
37480 64 65 66 69 6e 65 64 2c 20 74 68 6f 75 67 68 20  defined, though 
37490 68 61 72 6d 6c 65 73 73 2e 20 20 46 75 74 75 72  harmless.  Futur
374a0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
374b0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
374c0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
374d0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
374e0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
374f0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
37500 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  version..**.** I
37510 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
37520 61 20 42 4c 4f 42 20 6f 72 20 61 20 54 45 58 54  a BLOB or a TEXT
37530 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68   string, then th
37540 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
37550 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73  _bytes().** or s
37560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
37570 74 65 73 31 36 28 29 20 69 6e 74 65 72 66 61 63  tes16() interfac
37580 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
37590 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
375a0 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20  size.** of that 
375b0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
375c0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
375d0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
375e0 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
375f0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
37600 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
37610 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
37620 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
37630 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
37640 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
37650 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
37660 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
37670 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
37680 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
37690 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
376a0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
376b0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
376c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
376d0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
376e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
376f0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
37700 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
37710 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
37720 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
37730 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
37740 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
37750 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
37760 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
37770 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
37780 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
37790 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
377a0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
377b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
377c0 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
377d0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
377e0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
377f0 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
37800 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
37810 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
37820 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
37830 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
37840 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
37850 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
37860 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
37870 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
37880 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
37890 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
378a0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
378b0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
378c0 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
378d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
378e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
378f0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
37900 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
37910 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
37920 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
37930 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
37940 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
37950 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
37960 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
37970 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
37980 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
37990 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
379a0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
379b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
379c0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
379d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
379e0 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
379f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
37a00 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
37a10 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
37a20 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
37a30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
37a40 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
37a50 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
37a60 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
37a70 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
37a80 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
37a90 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
37aa0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
37ab0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
37ac0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
37ad0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
37ae0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
37af0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
37b00 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
37b10 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
37b20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
37b30 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
37b40 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
37b50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37b60 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
37b70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
37b80 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
37b90 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
37ba0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
37bb0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
37bc0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
37bd0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
37be0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
37bf0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
37c00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
37c10 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69  ..**.** <b>Warni
37c20 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a  ng:</b> ^The obj
37c30 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
37c40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
37c50 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
37c60 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
37c70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37c80 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74  ject.  In a mult
37c90 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f  ithreaded enviro
37ca0 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70  nment,.** an unp
37cb0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
37cc0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
37cd0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73  y only be used s
37ce0 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73  afely with.** [s
37cf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
37d00 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
37d10 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
37d20 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
37d30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37d40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
37d50 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
37d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
37d70 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
37d80 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
37d90 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
37da0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
37db0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
37dc0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
37dd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37de0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
37df0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
37e00 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  )], the behavior
37e10 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
37e20 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68  fe..** Hence, th
37e30 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
37e40 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
37e50 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c  ce.** is normall
37e60 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77 69  y only useful wi
37e70 74 68 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65  thin the impleme
37e80 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b  ntation of .** [
37e90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37ea0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
37eb0 73 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74  s] or [virtual t
37ec0 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68  ables], not with
37ed0 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  in.** top-level 
37ee0 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
37ef0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73  ..**.** The thes
37f00 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 61  e routines may a
37f10 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
37f20 74 20 74 68 65 20 64 61 74 61 74 79 70 65 20 6f  t the datatype o
37f30 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  f the result..**
37f40 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69   ^For example, i
37f50 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
37f60 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
37f70 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
37f80 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
37f90 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
37fa0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
37fb0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
37fc0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
37fd0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
37fe0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
37ff0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
38000 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
38010 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
38020 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
38030 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
38040 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
38050 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
38060 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
38070 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
38080 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
38090 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
380a0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
380b0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
380c0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
380d0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
380e0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
380f0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
38100 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
38110 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
38120 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
38130 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
38140 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
38150 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
38160 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
38170 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
38180 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
38190 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
381a0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
381b0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
381c0 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
381d0 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
381e0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
381f0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
38200 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
38210 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
38220 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
38230 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
38240 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
38250 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
38260 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
38270 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
38280 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
38290 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
382a0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
382b0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
382c0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
382d0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
382e0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
382f0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
38300 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
38310 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
38320 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
38330 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
38340 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
38350 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
38360 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
38370 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
38380 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
38390 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
383a0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
383b0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
383c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
383d0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
383e0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
383f0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
38400 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
38410 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
38420 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
38430 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
38440 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
38450 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
38460 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
38470 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
38480 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
38490 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
384a0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
384b0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
384c0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
384d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
384e0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
384f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
38500 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
38510 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
38520 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
38530 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
38540 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
38550 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
38560 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
38570 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
38580 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
38590 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
385a0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
385b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
385c0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
385d0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
385e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
385f0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
38600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
38610 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
38620 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
38630 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
38640 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
38650 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
38660 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
38670 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
38680 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
38690 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
386a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
386b0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
386c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
386d0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
386e0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
386f0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
38700 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
38710 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
38720 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
38730 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
38740 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
38750 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**